sphinx: ada: port to Sphinx

gcc/ada/ChangeLog:

	* doc/gnat-style.rst: Moved to...
	* doc/gnat-style/index.rst: ...here.
	* doc/gnat_rm.rst: Moved to...
	* doc/gnat_rm/index.rst: ...here.
	* doc/gnat_ugn.rst: Moved to...
	* doc/gnat_ugn/index.rst: ...here.
	* doc/share/latex_elements.py: Moved to...
	* doc/share/ada_latex_elements.py: ...here.
	* gcc-interface/Make-lang.in:
	* doc/Makefile: Removed.
	* doc/share/conf.py: Removed.
	* doc/share/gnu_free_documentation_license.rst: Removed.
	* gnat-style.texi: Removed.
	* gnat_rm.texi: Removed.
	* gnat_ugn.texi: Removed.
	* doc/gnat-style/conf.py: New file.
	* doc/gnat-style/gnu_free_documentation_license.rst: New file.
	* doc/gnat_rm/conf.py: New file.
	* doc/gnat_rm/gnu_free_documentation_license.rst: New file.
	* doc/gnat_ugn/conf.py: New file.
	* doc/gnat_ugn/gnu_free_documentation_license.rst: New file.
	* doc/share/adabaseconf.py: New file.
	* doc/gnat_rm/security_hardening_features.rst: Add role.
	* doc/gnat_ugn/platform_specific_information.rst: Remove
	  duplicate definition of |nbsp|.

diff --git a/gcc/ada/doc/Makefile b/gcc/ada/doc/Makefile
deleted file mode 100644 (file)
index 4adfd36..0000000
--- a/gcc/ada/doc/Makefile
+++ /dev/null
@@ -1,87 +0,0 @@
-# Makefile for Sphinx documentation
-
-# You can set these variables from the command line.
-SPHINXOPTS    = -W
-SPHINXBUILD   = DOC_NAME=$* sphinx-build
-PAPER         =
-BUILDDIR      = build
-SOURCEDIR     = .
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) \
-                 -c $(SOURCEDIR)/share \
-                 -d $(BUILDDIR)/$*/doctrees \
-                 $(SOURCEDIR)
-DOC_LIST=gnat_rm gnat_ugn gnat-style
-FMT_LIST=html pdf txt info
-
-.PHONY: help clean
-
-help:
-       @echo "Please use \`make <target>' where <target> is one of"
-       @echo "  DOC_NAME.html       to make standalone HTML files"
-       @echo "  DOC_NAME.pdf        to make LaTeX files and run them through pdflatex"
-       @echo "  DOC_NAME.txt        to make text files"
-       @echo "  DOC_NAME.info       to make info files"
-       @echo "  DOC_NAME.texinfo    to make Texinfo files"
-       @echo "  DOC_NAME.all        to build DOC_NAME for all previous formats"
-       @echo "  all                 to build all documentations in all formats"
-       @echo "  html-all            same as previous rule but only for HTML format"
-       @echo "  pdf-all             same as previous rule but only for PDF format"
-       @echo "  txt-all             same as previous rule but only for text format"
-       @echo "  info-all            same as previous rule but only for info format"
-       @echo "  texinfo-all         same as previous rule but only for texinfo format"
-       @echo ""
-       @echo "DOC_NAME should be a documentation name in the following list:"
-       @echo "  $(DOC_LIST)"
-       @echo ""
-       @echo "source and location can be overridden using SOURCEDIR and BUILDDIR variables"
-
-clean:
-       -rm -rf $(BUILDDIR)
-
-.PHONY: mk_empty_dirs
-mk_empty_dirs:
-       mkdir -p share/_static
-
-%.html: mk_empty_dirs
-       $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$*/html
-
-%.pdf: mk_empty_dirs
-       $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/$*/pdf
-       $(MAKE) -C $(BUILDDIR)/$*/pdf all-pdf LATEXOPTS="-interaction=nonstopmode"
-
-%.txt: mk_empty_dirs
-       $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/txt
-       $(MAKE) -C $(BUILDDIR)/$*/txt plaintext
-
-%.info: mk_empty_dirs
-       $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/info
-       $(MAKE) -C $(BUILDDIR)/$*/info info
-
-%.texinfo: mk_empty_dirs
-       $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/texinfo
-       sed -e 's/^@dircategory/@dircategory GNU Ada Tools/g' < $(BUILDDIR)/$*/texinfo/$*.texi > $(BUILDDIR)/../../$*.texi
-
-.PHONY: html-all
-html-all: $(foreach doc, $(DOC_LIST), $(doc).html)
-
-.PHONY: pdf-all
-pdf-all: $(foreach doc, $(DOC_LIST), $(doc).pdf)
-
-.PHONY: txt-all
-txt-all: $(foreach doc, $(DOC_LIST), $(doc).txt)
-
-.PHONY: info-all
-info-all: $(foreach doc, $(DOC_LIST), $(doc).info)
-
-.PHONY: texinfo-all
-texinfo-all: $(foreach doc, $(DOC_LIST), $(doc).texinfo)
-
-%.all:
-       $(MAKE) $(foreach fmt, $(FMT_LIST), $*.$(fmt))
-
-.PHONY: all
-all: $(foreach fmt, $(FMT_LIST), $(fmt)-all)

diff --git a/gcc/ada/doc/gnat-style/conf.py b/gcc/ada/doc/gnat-style/conf.py
new file mode 100644 (file)
index 0000000..a413d26
--- /dev/null
+++ b/gcc/ada/doc/gnat-style/conf.py
@@ -0,0 +1,26 @@
+# Configuration file for the Sphinx documentation builder.
+
+import sys
+sys.path.append('../share')
+
+from adabaseconf import *
+
+name = 'gnat-style'
+project = 'GNAT Coding Style: A Guide for GNAT Developers'
+authors = 'AdaCore'
+
+set_latex_elements(latex_elements, project)
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+latex_documents = [
+  ('index', f'{name}.tex', project, authors, 'manual'),
+]
+
+texinfo_documents = [
+  ('index', name, project, authors, None, None, None, True)
+]
+
+tags.add(get_gnat_build_type())
+set_common(name, globals())

diff --git a/gcc/ada/doc/gnat-style/gnu_free_documentation_license.rst b/gcc/ada/doc/gnat-style/gnu_free_documentation_license.rst
new file mode 100644 (file)
index 0000000..33c62cf
--- /dev/null
+++ b/gcc/ada/doc/gnat-style/gnu_free_documentation_license.rst
@@ -0,0 +1 @@
+.. include:: ../../../../doc/gnu_free_documentation_license.rst

diff --git a/gcc/ada/doc/gnat-style.rst b/gcc/ada/doc/gnat-style/index.rst
similarity index 99%
rename from gcc/ada/doc/gnat-style.rst
rename to gcc/ada/doc/gnat-style/index.rst
index 527e7ba2a66d7b2df71eb6d6ca2a88cb784578ad..b9428749f1f81c76778895d2f4cfc6de43215d86 100644 (file)
--- a/gcc/ada/doc/gnat-style.rst
+++ b/gcc/ada/doc/gnat-style/index.rst
@@ -688,4 +688,4 @@ Program Structure and Compilation Issues
   .. index:: krunch.ads file
 
 .. toctree::
-   share/gnu_free_documentation_license
+   gnu_free_documentation_license

diff --git a/gcc/ada/doc/gnat_rm/conf.py b/gcc/ada/doc/gnat_rm/conf.py
new file mode 100644 (file)
index 0000000..e99d1e6
--- /dev/null
+++ b/gcc/ada/doc/gnat_rm/conf.py
@@ -0,0 +1,26 @@
+# Configuration file for the Sphinx documentation builder.
+
+import sys
+sys.path.append('../share')
+
+from adabaseconf import *
+
+name = 'gnat_rm'
+project = 'GNAT Reference Manual'
+authors = 'AdaCore'
+
+set_latex_elements(latex_elements, project)
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+latex_documents = [
+  ('index', f'{name}.tex', project, authors, 'manual'),
+]
+
+texinfo_documents = [
+  ('index', name, project, authors, None, None, None, True)
+]
+
+tags.add(get_gnat_build_type())
+set_common(name, globals())

diff --git a/gcc/ada/doc/gnat_rm/gnu_free_documentation_license.rst b/gcc/ada/doc/gnat_rm/gnu_free_documentation_license.rst
new file mode 100644 (file)
index 0000000..33c62cf
--- /dev/null
+++ b/gcc/ada/doc/gnat_rm/gnu_free_documentation_license.rst
@@ -0,0 +1 @@
+.. include:: ../../../../doc/gnu_free_documentation_license.rst

diff --git a/gcc/ada/doc/gnat_rm.rst b/gcc/ada/doc/gnat_rm/index.rst
similarity index 54%
rename from gcc/ada/doc/gnat_rm.rst
rename to gcc/ada/doc/gnat_rm/index.rst
index 7743ef8b5f437cbe6858bd1c55cd6af65e979f2f..6c2616a0f1c016e869c15322b8c5965aaf104650 100644 (file)
--- a/gcc/ada/doc/gnat_rm.rst
+++ b/gcc/ada/doc/gnat_rm/index.rst
@@ -39,25 +39,25 @@ GNAT Reference Manual
    :numbered:
    :maxdepth: 3
 
-   gnat_rm/about_this_guide
-   gnat_rm/implementation_defined_pragmas
-   gnat_rm/implementation_defined_aspects
-   gnat_rm/implementation_defined_attributes
-   gnat_rm/standard_and_implementation_defined_restrictions
-   gnat_rm/implementation_advice
-   gnat_rm/implementation_defined_characteristics
-   gnat_rm/intrinsic_subprograms
-   gnat_rm/representation_clauses_and_pragmas
-   gnat_rm/standard_library_routines
-   gnat_rm/the_implementation_of_standard_i_o
-   gnat_rm/the_gnat_library
-   gnat_rm/interfacing_to_other_languages
-   gnat_rm/specialized_needs_annexes
-   gnat_rm/implementation_of_specific_ada_features
-   gnat_rm/implementation_of_ada_2012_features
-   gnat_rm/security_hardening_features
-   gnat_rm/obsolescent_features
-   gnat_rm/compatibility_and_porting_guide
+   about_this_guide
+   implementation_defined_pragmas
+   implementation_defined_aspects
+   implementation_defined_attributes
+   standard_and_implementation_defined_restrictions
+   implementation_advice
+   implementation_defined_characteristics
+   intrinsic_subprograms
+   representation_clauses_and_pragmas
+   standard_library_routines
+   the_implementation_of_standard_i_o
+   the_gnat_library
+   interfacing_to_other_languages
+   specialized_needs_annexes
+   implementation_of_specific_ada_features
+   implementation_of_ada_2012_features
+   security_hardening_features
+   obsolescent_features
+   compatibility_and_porting_guide
 
 .. raw:: latex
 
@@ -66,4 +66,4 @@ GNAT Reference Manual
 .. toctree::
    :maxdepth: 3
 
-   share/gnu_free_documentation_license
+   gnu_free_documentation_license

diff --git a/gcc/ada/doc/gnat_rm/security_hardening_features.rst b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
index d7c02b94f36d2f7e06d8edfef1c23a4e842db69d..5a1f2d46326e82a9a40186b750e5115ec0bbe6c8 100644 (file)
--- a/gcc/ada/doc/gnat_rm/security_hardening_features.rst
+++ b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
@@ -1,3 +1,5 @@
+.. role:: switch(samp)
+
 .. _Security_Hardening_Features:
 
 ***************************

diff --git a/gcc/ada/doc/gnat_ugn/conf.py b/gcc/ada/doc/gnat_ugn/conf.py
new file mode 100644 (file)
index 0000000..94e3c07
--- /dev/null
+++ b/gcc/ada/doc/gnat_ugn/conf.py
@@ -0,0 +1,26 @@
+# Configuration file for the Sphinx documentation builder.
+
+import sys
+sys.path.append('../share')
+
+from adabaseconf import *
+
+name = 'gnat_ugn'
+project = "GNAT User's Guide for Native Platforms"
+authors = 'AdaCore'
+
+set_latex_elements(latex_elements, project)
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+latex_documents = [
+  ('index', f'{name}.tex', project, authors, 'manual'),
+]
+
+texinfo_documents = [
+  ('index', name, project, authors, None, None, None, True)
+]
+
+tags.add(get_gnat_build_type())
+set_common(name, globals())

diff --git a/gcc/ada/doc/gnat_ugn/gnu_free_documentation_license.rst b/gcc/ada/doc/gnat_ugn/gnu_free_documentation_license.rst
new file mode 100644 (file)
index 0000000..33c62cf
--- /dev/null
+++ b/gcc/ada/doc/gnat_ugn/gnu_free_documentation_license.rst
@@ -0,0 +1 @@
+.. include:: ../../../../doc/gnu_free_documentation_license.rst

diff --git a/gcc/ada/doc/gnat_ugn.rst b/gcc/ada/doc/gnat_ugn/index.rst
similarity index 63%
rename from gcc/ada/doc/gnat_ugn.rst
rename to gcc/ada/doc/gnat_ugn/index.rst
index 0ac68763760f538a2d49db06ce262702c3554871..d3d1dac3569e4a32ad8beee0eef67e56d671d8b5 100644 (file)
--- a/gcc/ada/doc/gnat_ugn.rst
+++ b/gcc/ada/doc/gnat_ugn/index.rst
@@ -40,12 +40,12 @@ GNAT User's Guide for Native Platforms
    :maxdepth: 3
    :numbered:
 
-   gnat_ugn/about_this_guide
-   gnat_ugn/getting_started_with_gnat
-   gnat_ugn/the_gnat_compilation_model
-   gnat_ugn/building_executable_programs_with_gnat
-   gnat_ugn/gnat_utility_programs
-   gnat_ugn/gnat_and_program_execution
+   about_this_guide
+   getting_started_with_gnat
+   the_gnat_compilation_model
+   building_executable_programs_with_gnat
+   gnat_utility_programs
+   gnat_and_program_execution
 
 .. raw:: latex
 
@@ -54,10 +54,10 @@ GNAT User's Guide for Native Platforms
 .. toctree::
    :maxdepth: 3
 
-   A. Platform-Specific Information <gnat_ugn/platform_specific_information>
-   B. Example of Binder Output <gnat_ugn/example_of_binder_output>
-   C. Elaboration Order Handling in GNAT <gnat_ugn/elaboration_order_handling_in_gnat>
-   D. Inline Assembler <gnat_ugn/inline_assembler>
-   E. GNU Free Documentation License <share/gnu_free_documentation_license>
+   A. Platform-Specific Information <platform_specific_information>
+   B. Example of Binder Output <example_of_binder_output>
+   C. Elaboration Order Handling in GNAT <elaboration_order_handling_in_gnat>
+   D. Inline Assembler <inline_assembler>
+   E. GNU Free Documentation License <gnu_free_documentation_license>
 
 

diff --git a/gcc/ada/doc/gnat_ugn/platform_specific_information.rst b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst
index 4d25dea3d1e784a3dc472279a763031702234245..3ada65ddade006e9dee261c2726b6d28f0ed123d 100644 (file)
--- a/gcc/ada/doc/gnat_ugn/platform_specific_information.rst
+++ b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst
@@ -1,11 +1,5 @@
 .. role:: switch(samp)
 
-.. -- Non-breaking space in running text
-   -- E.g. Ada |nbsp| 95
-
-.. |nbsp| unicode:: 0xA0
-   :trim:
-
 .. _Platform_Specific_Information:
 
 *****************************

diff --git a/gcc/ada/doc/share/latex_elements.py b/gcc/ada/doc/share/ada_latex_elements.py
similarity index 87%
rename from gcc/ada/doc/share/latex_elements.py
rename to gcc/ada/doc/share/ada_latex_elements.py
index f23b2aff6be1ec87261880e5253b04247c68b4f2..9578c0296af4596b164168d79d9cd0eed76d4f8a 100644 (file)
--- a/gcc/ada/doc/share/latex_elements.py
+++ b/gcc/ada/doc/share/ada_latex_elements.py
@@ -1,5 +1,9 @@
 # define some latex elements to be used for PDF output
 
+import os
+
+folder = os.path.dirname(os.path.realpath(__file__))
+
 PAGE_BLANK = r'''
 \makeatletter
 \def\cleartooddpage{%%
@@ -46,7 +50,7 @@ TOC_CMD = r'''
 \makeatother
 '''
 
-with open('copyright.tex', 'r') as fd:
+with open(os.path.join(folder, 'copyright.tex'), 'r') as fd:
     copyright = fd.read()
 
 TOC = r'''
@@ -62,6 +66,11 @@ LATEX_HYPHEN = r'''
 \tolerance=1000
 '''
 
+ENCLOSE = r'''
+@definfoenclose strong,*,*
+@definfoenclose emph,','
+'''
+
 
 def doc_settings(full_document_name, version):
     return '\n'.join([

diff --git a/gcc/ada/doc/share/adabaseconf.py b/gcc/ada/doc/share/adabaseconf.py
new file mode 100644 (file)
index 0000000..4a80a83
--- /dev/null
+++ b/gcc/ada/doc/share/adabaseconf.py
@@ -0,0 +1,81 @@
+# GNAT build configuration file
+
+import sys
+sys.path.append('.')
+sys.path.append('../../../../doc')
+
+from baseconf import *
+
+import os
+import re
+import sys
+import time
+
+import ada_latex_elements
+
+import ada_pygments
+
+gnatvsn_content = read_file('ada/gnatvsn.ads')
+
+
+def get_gnat_version():
+    m = re.search(r'Gnat_Static_Version_String : ' +
+                  r'constant String := "([^\(\)]+)\(.*\)?";',
+                  gnatvsn_content)
+    if m:
+        return m.group(1).strip()
+    else:
+        return gcc_BASEVER
+
+
+def get_gnat_build_type():
+    m = re.search(r'Build_Type : constant Gnat_Build_Type := (.+);',
+                  gnatvsn_content)
+    if m:
+        return {'Gnatpro': 'PRO',
+                'FSF': 'FSF',
+                'GPL': 'GPL'}[m.group(1).strip()]
+    else:
+        print('cannot compute GNAT build type')
+        sys.exit(1)
+
+
+copyright = '2008-%s, Free Software Foundation' % YEAR
+
+version = get_gnat_version()
+release = get_gnat_version()
+
+if os.path.isfile('adacore_transparent.png'):
+    html_logo = 'adacore_transparent.png'
+if os.path.isfile('favicon.ico'):
+    html_favicon = 'favicon.ico'
+
+latex_additional_files = ['../share/gnat.sty']
+
+copyright_macros = {
+    'date': time.strftime('%b %d, %Y'),
+    'edition': 'GNAT %s Edition' % 'Pro' if get_gnat_build_type() == 'PRO'
+               else 'GPL',
+    'name': 'GNU Ada',
+    'tool': 'GNAT',
+    'version': version}
+
+
+def set_latex_elements(latex_elements, title):
+    elements = {
+        'preamble': '\\usepackage{gnat}\n' +
+        ada_latex_elements.TOC_DEPTH +
+        ada_latex_elements.PAGE_BLANK +
+        ada_latex_elements.TOC_CMD +
+        ada_latex_elements.LATEX_HYPHEN +
+        ada_latex_elements.doc_settings(title, get_gnat_version()),
+        'tableofcontents': ada_latex_elements.TOC % copyright_macros
+    }
+    for key, value in elements.items():
+        latex_elements.setdefault(key, '')
+        latex_elements[key] += value
+
+
+def setup(app):
+    app.add_lexer('ada', ada_pygments.AdaLexer)
+    app.add_lexer('gpr', ada_pygments.GNATProjectLexer)

diff --git a/gcc/ada/doc/share/conf.py b/gcc/ada/doc/share/conf.py
deleted file mode 100644 (file)
index bb36bfa..0000000
--- a/gcc/ada/doc/share/conf.py
+++ /dev/null
@@ -1,148 +0,0 @@
-# -*- coding: utf-8 -*-
-# Style_Check:Python_Fragment (meaning no pyflakes check)
-#
-# GNAT build configuration file
-
-import sys
-import os
-import time
-import re
-
-sys.path.append('.')
-
-import ada_pygments
-import latex_elements
-
-# Some configuration values for the various documentation handled by
-# this conf.py
-
-DOCS = {
-    'gnat_rm': {
-        'title': 'GNAT Reference Manual'},
-    'gnat_ugn': {
-        'title': 'GNAT User\'s Guide for Native Platforms'},
-    'gnat-style': {
-        'title': 'GNAT Coding Style: A Guide for GNAT Developers'}}
-
-# Then retrieve the source directory
-root_source_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-gnatvsn_spec = os.path.join(root_source_dir, '..', 'gnatvsn.ads')
-basever = os.path.join(root_source_dir, '..', '..', 'BASE-VER')
-texi_fsf = True  # Set to False when FSF doc is switched to sphinx by default
-
-with open(gnatvsn_spec, 'r') as fd:
-    gnatvsn_content = fd.read()
-
-
-def get_copyright():
-    return '2008-%s, Free Software Foundation' % time.strftime('%Y')
-
-
-def get_gnat_version():
-    m = re.search(r'Gnat_Static_Version_String : ' +
-                  r'constant String := "([^\(\)]+)\(.*\)?";',
-                  gnatvsn_content)
-    if m:
-        return m.group(1).strip()
-    else:
-        if texi_fsf and os.path.exists(basever):
-            return ''
-
-        try:
-            with open(basever) as fd:
-                return fd.read()
-        except Exception:
-            pass
-
-    print('cannot find GNAT version in gnatvsn.ads or in ' + basever)
-    sys.exit(1)
-
-
-def get_gnat_build_type():
-    m = re.search(r'Build_Type : constant Gnat_Build_Type := (.+);',
-                  gnatvsn_content)
-    if m:
-        return {'Gnatpro': 'PRO',
-                'FSF': 'FSF',
-                'GPL': 'GPL'}[m.group(1).strip()]
-    else:
-        print('cannot compute GNAT build type')
-        sys.exit(1)
-
-
-# First retrieve the name of the documentation we are building
-doc_name = os.environ.get('DOC_NAME', None)
-if doc_name is None:
-    print('DOC_NAME environment variable should be set')
-    sys.exit(1)
-
-if doc_name not in DOCS:
-    print('%s is not a valid documentation name' % doc_name)
-    sys.exit(1)
-
-
-# Exclude sources that are not part of the current documentation
-exclude_patterns = []
-for d in os.listdir(root_source_dir):
-    if d not in ('share', doc_name, doc_name + '.rst'):
-        exclude_patterns.append(d)
-        print('ignoring %s' % d)
-
-if doc_name == 'gnat_rm':
-    exclude_patterns.append('share/gnat_project_manager.rst')
-    print('ignoring share/gnat_project_manager.rst')
-
-extensions = []
-templates_path = ['_templates']
-source_suffix = '.rst'
-master_doc = doc_name
-
-# General information about the project.
-project = DOCS[doc_name]['title']
-
-copyright = get_copyright()
-
-version = get_gnat_version()
-release = get_gnat_version()
-
-pygments_style = None
-tags.add(get_gnat_build_type())
-html_theme = 'sphinxdoc'
-if os.path.isfile('adacore_transparent.png'):
-    html_logo = 'adacore_transparent.png'
-if os.path.isfile('favicon.ico'):
-    html_favicon = 'favicon.ico'
-
-html_static_path = ['_static']
-
-latex_additional_files = ['gnat.sty']
-
-copyright_macros = {
-    'date': time.strftime("%b %d, %Y"),
-    'edition': 'GNAT %s Edition' % 'Pro' if get_gnat_build_type() == 'PRO'
-               else 'GPL',
-    'name': 'GNU Ada',
-    'tool': 'GNAT',
-    'version': version}
-
-latex_elements = {
-    'preamble': '\\usepackage{gnat}\n' +
-    latex_elements.TOC_DEPTH +
-    latex_elements.PAGE_BLANK +
-    latex_elements.TOC_CMD +
-    latex_elements.LATEX_HYPHEN +
-    latex_elements.doc_settings(DOCS[doc_name]['title'],
-                                get_gnat_version()),
-    'tableofcontents': latex_elements.TOC % copyright_macros}
-
-latex_documents = [
-    (master_doc, '%s.tex' % doc_name, project, 'AdaCore', 'manual')]
-
-texinfo_documents = [
-    (master_doc, doc_name, project,
-     'AdaCore', doc_name, doc_name, '')]
-
-
-def setup(app):
-    app.add_lexer('ada', ada_pygments.AdaLexer)
-    app.add_lexer('gpr', ada_pygments.GNATProjectLexer)

diff --git a/gcc/ada/doc/share/gnu_free_documentation_license.rst b/gcc/ada/doc/share/gnu_free_documentation_license.rst
deleted file mode 100644 (file)
index 0235545..0000000
--- a/gcc/ada/doc/share/gnu_free_documentation_license.rst
+++ /dev/null
@@ -1,458 +0,0 @@
-.. _gnu_fdl:
-
-******************************
-GNU Free Documentation License
-******************************
-
-Version 1.3, 3 November 2008
-
-Copyright  2000, 2001, 2002, 2007, 2008  Free Software Foundation, Inc
-https://fsf.org/
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-
-**Preamble**
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document "free" in the sense of freedom: to
-assure everyone the effective freedom to copy and redistribute it,
-with or without modifying it, either commercially or noncommercially.
-Secondarily, this License preserves for the author and publisher a way
-to get credit for their work, while not being considered responsible
-for modifications made by others.
-
-This License is a kind of "copyleft", which means that derivative
-works of the document must themselves be free in the same sense.  It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does.  But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book.  We recommend this License
-principally for works whose purpose is instruction or reference.
-
-**1. APPLICABILITY AND DEFINITIONS**
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License.  Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein.  The **Document**, below,
-refers to any such manual or work.  Any member of the public is a
-licensee, and is addressed as "**you**".  You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-A "**Modified Version**" of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A "**Secondary Section**" is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject.  (Thus, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.)  The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The "**Invariant Sections**" are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License.  If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant.  The Document may contain zero
-Invariant Sections.  If the Document does not identify any Invariant
-Sections then there are none.
-
-The "**Cover Texts**" are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License.  A Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A "**Transparent**" copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters.  A copy made in an otherwise Transparent file
-format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text.  A copy that is not "Transparent" is called **Opaque**.
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML, PostScript or PDF designed for human modification.  Examples of
-transparent image formats include PNG, XCF and JPG.  Opaque formats
-include proprietary formats that can be read and edited only by
-proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated HTML, PostScript or PDF produced by some word
-processors for output purposes only.
-
-The "**Title Page**" means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page.  For works in
-formats which do not have any title page as such, "Title Page" means
-the text near the most prominent appearance of the work's title,
-preceding the beginning of the body of the text.
-
-The "**publisher**" means any person or entity that distributes
-copies of the Document to the public.
-
-A section "**Entitled XYZ**" means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language.  (Here XYZ stands for a
-specific section name mentioned below, such as "**Acknowledgements**",
-"**Dedications**", "**Endorsements**", or "**History**".)
-To "**Preserve the Title**"
-of such a section when you modify the Document means that it remains a
-section "Entitled XYZ" according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document.  These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-
-**2. VERBATIM COPYING**
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License.  You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute.  However, you may accept
-compensation in exchange for copies.  If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
-**3. COPYING IN QUANTITY**
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) of the Document, numbering more than 100, and the
-Document's license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover.  Both covers must also clearly and legibly identify
-you as the publisher of these copies.  The front cover must present
-the full title with all words of the title equally prominent and
-visible.  You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-If you use the latter option, you must take reasonably prudent steps,
-when you begin distribution of Opaque copies in quantity, to ensure
-that this Transparent copy will remain thus accessible at the stated
-location until at least one year after the last time you distribute an
-Opaque copy (directly or through your agents or retailers) of that
-edition to the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
-**4. MODIFICATIONS**
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it.  In addition, you must do these things in the Modified Version:
-
-A. Use in the Title Page (and on the covers, if any) a title distinct
-   from that of the Document, and from those of previous versions
-   (which should, if there were any, be listed in the History section
-   of the Document).  You may use the same title as a previous version
-   if the original publisher of that version gives permission.
-
-B. List on the Title Page, as authors, one or more persons or entities
-   responsible for authorship of the modifications in the Modified
-   Version, together with at least five of the principal authors of the
-   Document (all of its principal authors, if it has fewer than five),
-   unless they release you from this requirement.
-
-C. State on the Title page the name of the publisher of the
-   Modified Version, as the publisher.
-
-D. Preserve all the copyright notices of the Document.
-
-E. Add an appropriate copyright notice for your modifications
-   adjacent to the other copyright notices.
-
-F. Include, immediately after the copyright notices, a license notice
-   giving the public permission to use the Modified Version under the
-   terms of this License, in the form shown in the Addendum below.
-
-G. Preserve in that license notice the full lists of Invariant Sections
-   and required Cover Texts given in the Document's license notice.
-H. Include an unaltered copy of this License.
-
-I. Preserve the section Entitled "History", Preserve its Title, and add
-   to it an item stating at least the title, year, new authors, and
-   publisher of the Modified Version as given on the Title Page.  If
-   there is no section Entitled "History" in the Document, create one
-   stating the title, year, authors, and publisher of the Document as
-   given on its Title Page, then add an item describing the Modified
-   Version as stated in the previous sentence.
-
-J. Preserve the network location, if any, given in the Document for
-   public access to a Transparent copy of the Document, and likewise
-   the network locations given in the Document for previous versions
-   it was based on.  These may be placed in the "History" section.
-   You may omit a network location for a work that was published at
-   least four years before the Document itself, or if the original
-   publisher of the version it refers to gives permission.
-
-K. For any section Entitled "Acknowledgements" or "Dedications",
-   Preserve the Title of the section, and preserve in the section all
-   the substance and tone of each of the contributor acknowledgements
-   and/or dedications given therein.
-
-L. Preserve all the Invariant Sections of the Document,
-   unaltered in their text and in their titles.  Section numbers
-   or the equivalent are not considered part of the section titles.
-
-M. Delete any section Entitled "Endorsements".  Such a section
-   may not be included in the Modified Version.
-
-N. Do not retitle any existing section to be Entitled "Endorsements"
-   or to conflict in title with any Invariant Section.
-
-O. Preserve any Warranty Disclaimers.
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant.  To do this, add their titles to the
-list of Invariant Sections in the Modified Version's license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section Entitled "Endorsements", provided it contains
-nothing but endorsements of your Modified Version by various
-parties---for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version.  Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity.  If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
-**5. COMBINING DOCUMENTS**
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice, and that you preserve all their Warranty Disclaimers.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy.  If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled "History"
-in the various original documents, forming one section Entitled
-"History"; likewise combine any sections Entitled "Acknowledgements",
-and any sections Entitled "Dedications".  You must delete all sections
-Entitled "Endorsements".
-
-**6. COLLECTIONS OF DOCUMENTS**
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
-**7. AGGREGATION WITH INDEPENDENT WORKS**
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, is called an "aggregate" if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation's users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which are not themselves
-derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one half of
-the entire aggregate, the Document's Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-
-**8. TRANSLATION**
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections.  You may include a
-translation of this License, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers.  In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled "Acknowledgements",
-"Dedications", or "History", the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-
-**9. TERMINATION**
-
-You may not copy, modify, sublicense, or distribute the Document
-except as expressly provided under this License.  Any attempt
-otherwise to copy, modify, sublicense, or distribute it is void, and
-will automatically terminate your rights under this License.
-
-However, if you cease all violation of this License, then your license
-from a particular copyright holder is reinstated (a) provisionally,
-unless and until the copyright holder explicitly and finally
-terminates your license, and (b) permanently, if the copyright holder
-fails to notify you of the violation by some reasonable means prior to
-60 days after the cessation.
-
-Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, receipt of a copy of some or all of the same material does
-not give you any rights to use it.
-
-**10. FUTURE REVISIONS OF THIS LICENSE**
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time.  Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.  See
-https://www.gnu.org/copyleft/.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License "or any later version" applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation.  If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.  If the Document
-specifies that a proxy can decide which future versions of this
-License can be used, that proxy's public statement of acceptance of a
-version permanently authorizes you to choose that version for the
-Document.
-
-**11. RELICENSING**
-
-"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
-World Wide Web server that publishes copyrightable works and also
-provides prominent facilities for anybody to edit those works.  A
-public wiki that anybody can edit is an example of such a server.  A
-"Massive Multiauthor Collaboration" (or "MMC") contained in the
-site means any set of copyrightable works thus published on the MMC
-site.
-
-"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
-license published by Creative Commons Corporation, a not-for-profit
-corporation with a principal place of business in San Francisco,
-California, as well as future copyleft versions of that license
-published by that same organization.
-
-"Incorporate" means to publish or republish a Document, in whole or
-in part, as part of another Document.
-
-An MMC is "eligible for relicensing" if it is licensed under this
-License, and if all works that were first published under this License
-somewhere other than this MMC, and subsequently incorporated in whole
-or in part into the MMC, (1) had no cover texts or invariant sections,
-and (2) were thus incorporated prior to November 1, 2008.
-
-The operator of an MMC Site may republish an MMC contained in the site
-under CC-BY-SA on the same site at any time before August 1, 2009,
-provided the MMC is eligible for relicensing.
-
-**ADDENDUM: How to use this License for your documents**
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
-    Copyright © YEAR  YOUR NAME.
-    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, no Front-Cover Texts, and no Back-Cover Texts.
-    A copy of the license is included in the section entitled "GNU
-    Free Documentation License".
-
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the "with ... Texts." line with this:
-
-    with the Invariant Sections being LIST THEIR TITLES, with the
-    Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.

diff --git a/gcc/ada/gcc-interface/Make-lang.in b/gcc/ada/gcc-interface/Make-lang.in
index 45a4168e890800e8ef1459e647be7dc04631a0dd..71a26e526277d45d0cf0160634d86a76804425be 100644 (file)
--- a/gcc/ada/gcc-interface/Make-lang.in
+++ b/gcc/ada/gcc-interface/Make-lang.in
@@ -808,32 +808,24 @@ ada.tags: force
 
 # Generate documentation.
 
-doc/gnat_ugn.info: ada/gnat_ugn.texi \
-   $(gcc_docdir)/include/fdl.texi $(gcc_docdir)/include/gcc-common.texi        \
-   gcc-vers.texi
-       if [ x$(BUILD_INFO) = xinfo ]; then \
-         rm -f $(@)*; \
-         $(MAKEINFO) $(MAKEINFOFLAGS) -I$(gcc_docdir)/include \
-            -I$(srcdir)/ada -o $@ $<; \
+doc/gnat_ugn/info/texinfo/gnat_ugn.info: $(SPHINX_FILES)
+       + if [ x$(SPHINX_BUILD) = xsphinx-build ]; then \
+         make -C $(srcdir)/../doc info SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_ugn BUILDDIR=$(objdir)/doc/gnat_ugn/info; \
        else true; fi
 
-doc/gnat_rm.info: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi      \
-   $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
-       if [ x$(BUILD_INFO) = xinfo ]; then \
-         rm -f $(@)*; \
-         $(MAKEINFO) $(MAKEINFOFLAGS) -I$(gcc_docdir)/include \
-            -I$(srcdir)/ada -o $@ $<; \
+doc/gnat_rm/info/texinfo/gnat_rm.info: $(SPHINX_FILES)
+       + if [ x$(SPHINX_BUILD) = xsphinx-build ]; then \
+         make -C $(srcdir)/../doc info SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_rm BUILDDIR=$(objdir)/doc/gnat_rm/info; \
        else true; fi
 
-doc/gnat-style.info: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi        \
-   $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
-       if [ x$(BUILD_INFO) = xinfo ]; then \
-         rm -f $(@)*; \
-         $(MAKEINFO) $(MAKEINFOFLAGS) -I$(gcc_docdir)/include \
-            -I$(srcdir)/ada -o $@ $<; \
+doc/gnat-style/info/texinfo/gnat-style.info: $(SPHINX_FILES)
+       + if [ x$(SPHINX_BUILD) = xsphinx-build ]; then \
+         make -C $(srcdir)/../doc info SOURCEDIR=$(abs_srcdir)/ada/doc/gnat-style BUILDDIR=$(objdir)/doc/gnat-style/info; \
        else true; fi
 
-ADA_INFOFILES = doc/gnat_ugn.info doc/gnat_rm.info doc/gnat-style.info
+ADA_INFOFILES = doc/gnat_ugn/info/texinfo/gnat_ugn.info \
+               doc/gnat_rm/info/texinfo/gnat_rm.info \
+               doc/gnat-style/info/texinfo/gnat-style.info
 
 ada.info: $(ADA_INFOFILES)
 
@@ -844,26 +836,33 @@ ada.install-info: $(DESTDIR)$(infodir)/gnat_ugn.info \
        $(DESTDIR)$(infodir)/gnat_rm.info \
        $(DESTDIR)$(infodir)/gnat-style.info
 
-ADA_DVIFILES = doc/gnat_ugn.dvi \
-               doc/gnat_rm.dvi doc/gnat-style.dvi
+$(DESTDIR)$(infodir)/gnat_ugn.info: doc/gnat_ugn/info/texinfo/gnat_ugn.info installdirs
+       -rm -f $@
+       -$(INSTALL_DATA) $< $@
 
-ada.dvi: $(ADA_DVIFILES)
+$(DESTDIR)$(infodir)/gnat_rm.info: doc/gnat_rm/info/texinfo/gnat_rm.info installdirs
+       -rm -f $@
+       -$(INSTALL_DATA) $< $@
 
-ada.install-dvi: $(ADA_DVIFILES)
-       @$(NORMAL_INSTALL)
-       test -z "$(dvidir)/gcc" || $(mkinstalldirs) "$(DESTDIR)$(dvidir)/gcc"
-       @list='$(ADA_DVIFILES)'; for p in $$list; do \
-         if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
-         f=$(dvi__strip_dir) \
-         echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/gcc/$$f'"; \
-         $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/gcc/$$f"; \
-       done
+$(DESTDIR)$(infodir)/gnat-style.info: doc/gnat-style/info/texinfo/gnat-style.info installdirs
+       -rm -f $@
+       -$(INSTALL_DATA) $< $@
 
-ADA_PDFFILES = doc/gnat_ugn.pdf \
-               doc/gnat_rm.pdf doc/gnat-style.pdf
+ADA_PDFFILES = doc/gnat_ugn/pdf/latex/gnat_ugn.pdf\
+              doc/gnat_rm/pdf/latex/gnat_rm.pdf \
+              doc/gnat-style/pdf/latex/gnat-style.pdf
 
 ada.pdf: $(ADA_PDFFILES)
 
+doc/gnat_ugn/pdf/latex/gnat_ugn.pdf: $(SPHINX_FILES)
+       + make -C $(srcdir)/../doc latexpdf SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_ugn BUILDDIR=$(objdir)/doc/gnat_ugn/pdf
+
+doc/gnat_rm/pdf/latex/gnat_rm.pdf: $(SPHINX_FILES)
+       + make -C $(srcdir)/../doc latexpdf SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_rm BUILDDIR=$(objdir)/doc/gnat_rm/pdf
+
+doc/gnat-style/pdf/latex/gnat-style.pdf: $(SPHINX_FILES)
+       + make -C $(srcdir)/../doc latexpdf SOURCEDIR=$(abs_srcdir)/ada/doc/gnat-style BUILDDIR=$(objdir)/doc/gnat-style/pdf
+
 ada.install-pdf: $(ADA_PDFFILES)
        @$(NORMAL_INSTALL)
        test -z "$(pdfdir)/gcc" || $(mkinstalldirs) "$(DESTDIR)$(pdfdir)/gcc"
@@ -874,33 +873,18 @@ ada.install-pdf: $(ADA_PDFFILES)
          $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/gcc/$$f"; \
        done
 
-ada.html:
+ada.html: doc/gnat_ugn/html/html/index.html doc/gnat_rm/html/html/index.html doc/gnat-style/html/html/index.html
 
-ada.install-html:
-
-doc/gnat_ugn.dvi: ada/gnat_ugn.texi \
-       $(gcc_docdir)/include/fdl.texi  \
-       $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
-       $(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $<
-
-doc/gnat_rm.dvi: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi       \
-       $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
-       $(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $<
+doc/gnat_ugn/html/html/index.html: $(SPHINX_FILES)
+       + make -C $(srcdir)/../doc html SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_ugn BUILDDIR=$(objdir)/doc/gnat_ugn/html
 
-doc/gnat-style.dvi: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi
-       $(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $<
+doc/gnat_rm/html/html/index.html: $(SPHINX_FILES)
+       + make -C $(srcdir)/../doc html SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_rm BUILDDIR=$(objdir)/doc/gnat_rm/html
 
-doc/gnat_ugn.pdf: ada/gnat_ugn.texi \
-       $(gcc_docdir)/include/fdl.texi  \
-       $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
-       $(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $<
+doc/gnat-style/html/html/index.html: $(SPHINX_FILES)
+       + make -C $(srcdir)/../doc html SOURCEDIR=$(abs_srcdir)/ada/doc/gnat-style BUILDDIR=$(objdir)/doc/gnat-style/html
 
-doc/gnat_rm.pdf: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi       \
-       $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
-       $(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $<
-
-doc/gnat-style.pdf: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi
-       $(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $<
+ada.install-html:
 
 # Install hooks:
 # gnat1 is installed elsewhere as part of $(COMPILERS).

diff --git a/gcc/ada/gnat-style.texi b/gcc/ada/gnat-style.texi
deleted file mode 100644 (file)
index f3b1c29..0000000
--- a/gcc/ada/gnat-style.texi
+++ /dev/null
@@ -1,1437 +0,0 @@
-\input texinfo   @c -*-texinfo-*-
-@c %**start of header
-@setfilename gnat-style.info
-@documentencoding UTF-8
-@ifinfo
-@*Generated by Sphinx 5.1.1.@*
-@end ifinfo
-@settitle GNAT Coding Style A Guide for GNAT Developers
-@defindex ge
-@paragraphindent 0
-@exampleindent 4
-@finalout
-@dircategory GNU Ada Tools 
-@direntry
-* gnat-style: (gnat-style.info). gnat-style
-@end direntry
-
-@c %**end of header
-
-@copying
-@quotation
-GNAT Coding Style: A Guide for GNAT Developers , Aug 25, 2022
-
-AdaCore
-
-Copyright @copyright{} 2008-2022, Free Software Foundation
-@end quotation
-
-@end copying
-
-@titlepage
-@title GNAT Coding Style A Guide for GNAT Developers
-@insertcopying
-@end titlepage
-@contents
-
-@c %** start of user preamble
-
-@c %** end of user preamble
-
-@ifnottex
-@node Top
-@top GNAT Coding Style A Guide for GNAT Developers
-@insertcopying
-@end ifnottex
-
-@c %**start of body
-@anchor{gnat-style doc}@anchor{0}
-@menu
-* General:: 
-* Lexical Elements:: 
-* Declarations and Types:: 
-* Expressions and Names:: 
-* Statements:: 
-* Subprograms:: 
-* Packages and Visibility Rules:: 
-* Program Structure and Compilation Issues:: 
-* Index:: 
-
-@end menu
-
-@node General,Lexical Elements,Top,Top
-@anchor{gnat-style general}@anchor{1}@anchor{gnat-style gnat-coding-style-a-guide-for-gnat-developers}@anchor{2}
-@chapter General
-
-
-Most of GNAT is written in Ada using a consistent style to ensure
-readability of the code.  This document has been written to help
-maintain this consistent style, while having a large group of developers
-work on the compiler.
-
-For the coding style in the C parts of the compiler and run time,
-see the GNU Coding Guidelines.
-
-This document is structured after the Ada Reference Manual.
-Those familiar with that document should be able to quickly
-lookup style rules for particular constructs.
-
-@node Lexical Elements,Declarations and Types,General,Top
-@anchor{gnat-style lexical-elements}@anchor{3}
-@chapter Lexical Elements
-
-
-@menu
-* Character Set and Separators:: 
-* Identifiers:: 
-* Numeric Literals:: 
-* Reserved Words:: 
-* Comments:: 
-
-@end menu
-
-@node Character Set and Separators,Identifiers,,Lexical Elements
-@anchor{gnat-style character-set-and-separators}@anchor{4}
-@section Character Set and Separators
-
-
-@geindex Character set
-
-@geindex ASCII
-
-@geindex Separators
-
-@geindex End-of-line
-
-@geindex Line length
-
-@geindex Indentation
-
-
-@itemize *
-
-@item 
-The character set used should be plain 7-bit ASCII.
-The only separators allowed are space and the end-of-line sequence.
-No other control character or format effector (such as @code{HT},
-@code{VT}, @code{FF} )
-should be used.
-The normal end-of-line sequence is used, which may be
-@code{LF}, @code{CR/LF} or @code{CR},
-depending on the host system.  An optional @code{SUB}
-( @code{16#1A#} ) may be present as the
-last character in the file on hosts using that character as file terminator.
-
-@item 
-Files that are checked in or distributed should be in host format.
-
-@item 
-A line should never be longer than 79 characters, not counting the line
-separator.
-
-@item 
-Lines must not have trailing blanks.
-
-@item 
-Indentation is 3 characters per level for @code{if} statements, loops, and
-@code{case} statements.
-For exact information on required spacing between lexical
-elements, see file style.adb.
-
-@geindex style.adb file
-@end itemize
-
-@node Identifiers,Numeric Literals,Character Set and Separators,Lexical Elements
-@anchor{gnat-style identifiers}@anchor{5}
-@section Identifiers
-
-
-
-@itemize *
-
-@item 
-Identifiers will start with an upper case letter, and each letter following
-an underscore will be upper case.
-
-@geindex Casing (for identifiers)
-
-Short acronyms may be all upper case.
-All other letters are lower case.
-An exception is for identifiers matching a foreign language.  In particular,
-we use all lower case where appropriate for C.
-
-@item 
-Use underscores to separate words in an identifier.
-
-@geindex Underscores
-
-@item 
-Try to limit your use of abbreviations in identifiers.
-It is ok to make a few abbreviations, explain what they mean, and then
-use them frequently, but don’t use lots of obscure abbreviations.  An
-example is the @code{ALI} word which stands for Ada Library
-Information and is by convention always written in upper-case when
-used in entity names.
-
-@example
-procedure Find_ALI_Files;
-@end example
-
-@item 
-Don’t use the variable name @code{I}, use @code{J} instead; @code{I} is too
-easily confused with @code{1} in some fonts.  Similarly don’t use the
-variable @code{O}, which is too easily mistaken for the number @code{0}.
-@end itemize
-
-@node Numeric Literals,Reserved Words,Identifiers,Lexical Elements
-@anchor{gnat-style numeric-literals}@anchor{6}
-@section Numeric Literals
-
-
-
-@itemize *
-
-@item 
-Numeric literals should include underscores where helpful for
-readability.
-
-@geindex Underscores
-
-@example
-1_000_000
-16#8000_0000#
-3.14159_26535_89793_23846
-@end example
-@end itemize
-
-@node Reserved Words,Comments,Numeric Literals,Lexical Elements
-@anchor{gnat-style reserved-words}@anchor{7}
-@section Reserved Words
-
-
-
-@itemize *
-
-@item 
-Reserved words use all lower case.
-
-@geindex Casing (for reserved words)
-
-@example
-return else
-@end example
-
-@item 
-The words @code{Access}, @code{Delta} and @code{Digits} are
-capitalized when used as attribute_designator.
-@end itemize
-
-@node Comments,,Reserved Words,Lexical Elements
-@anchor{gnat-style comments}@anchor{8}
-@section Comments
-
-
-
-@itemize *
-
-@item 
-A comment starts with @code{--} followed by two spaces.
-The only exception to this rule (i.e. one space is tolerated) is when the
-comment ends with a single space followed by @code{--}.
-It is also acceptable to have only one space between @code{--} and the start
-of the comment when the comment is at the end of a line,
-after some Ada code.
-
-@item 
-Every sentence in a comment should start with an upper-case letter (including
-the first letter of the comment).
-
-@geindex Casing (in comments)
-
-@item 
-When declarations are commented with ‘hanging’ comments, i.e.
-comments after the declaration, there is no blank line before the
-comment, and if it is absolutely necessary to have blank lines within
-the comments, e.g. to make paragraph separations within a single comment,
-these blank lines `do' have a @code{--} (unlike the
-normal rule, which is to use entirely blank lines for separating
-comment paragraphs).  The comment starts at same level of indentation
-as code it is commenting.
-
-@geindex Blank lines (in comments)
-
-@geindex Indentation
-
-@example
-z : Integer;
---  Integer value for storing value of z
---
---  The previous line was a blank line.
-@end example
-
-@item 
-Comments that are dubious or incomplete, or that comment on possibly
-wrong or incomplete code, should be preceded or followed by @code{???}.
-
-@item 
-Comments in a subprogram body must generally be surrounded by blank lines.
-An exception is a comment that follows a line containing a single keyword
-( @code{begin}, @code{else}, @code{loop} ):
-
-@example
-begin
-   --  Comment for the next statement
-
-   A := 5;
-
-   --  Comment for the B statement
-
-   B := 6;
-end;
-@end example
-
-@item 
-In sequences of statements, comments at the end of the lines should be
-aligned.
-
-@geindex Alignment (in comments)
-
-@example
-My_Identifier := 5;      --  First comment
-Other_Id := 6;           --  Second comment
-@end example
-
-@item 
-Short comments that fit on a single line are `not' ended with a
-period.  Comments taking more than a line are punctuated in the normal
-manner.
-
-@item 
-Comments should focus on `why' instead of `what'.
-Descriptions of what subprograms do go with the specification.
-
-@item 
-Comments describing a subprogram spec should specifically mention the
-formal argument names.  General rule: write a comment that does not
-depend on the names of things.  The names are supplementary, not
-sufficient, as comments.
-
-@item 
-`Do not' put two spaces after periods in comments.
-@end itemize
-
-@node Declarations and Types,Expressions and Names,Lexical Elements,Top
-@anchor{gnat-style declarations-and-types}@anchor{9}
-@chapter Declarations and Types
-
-
-
-@itemize *
-
-@item 
-In entity declarations, colons must be surrounded by spaces.  Colons
-should be aligned.
-
-@geindex Alignment (in declarations)
-
-@example
-Entity1   : Integer;
-My_Entity : Integer;
-@end example
-
-@item 
-Declarations should be grouped in a logical order.
-Related groups of declarations may be preceded by a header comment.
-
-@item 
-All local subprograms in a subprogram or package body should be declared
-before the first local subprogram body.
-
-@item 
-Do not declare local entities that hide global entities.
-
-@geindex Hiding of outer entities
-
-@item 
-Do not declare multiple variables in one declaration that spans lines.
-Start a new declaration on each line, instead.
-
-@item 
-The defining_identifiers of global declarations serve as
-comments of a sort.  So don’t choose terse names, but look for names
-that give useful information instead.
-
-@item 
-Local names can be shorter, because they are used only within
-one context, where comments explain their purpose.
-
-@item 
-When starting an initialization or default expression on the line that follows
-the declaration line, use 2 characters for indentation.
-
-@example
-Entity1 : Integer :=
-  Function_Name (Parameters, For_Call);
-@end example
-
-@item 
-If an initialization or default expression needs to be continued on subsequent
-lines, the continuations should be indented from the start of the expression.
-
-@example
-Entity1 : Integer := Long_Function_Name
-                       (parameters for call);
-@end example
-@end itemize
-
-@node Expressions and Names,Statements,Declarations and Types,Top
-@anchor{gnat-style expressions-and-names}@anchor{a}
-@chapter Expressions and Names
-
-
-
-@itemize *
-
-@item 
-Every operator must be surrounded by spaces. An exception is that
-this rule does not apply to the exponentiation operator, for which
-there are no specific layout rules. The reason for this exception
-is that sometimes it makes clearer reading to leave out the spaces
-around exponentiation.
-
-@geindex Operators
-
-@example
-E := A * B**2 + 3 * (C - D);
-@end example
-
-@item 
-Use parentheses where they clarify the intended association of operands
-with operators:
-
-@geindex Parenthesization of expressions
-
-@example
-(A / B) * C
-@end example
-@end itemize
-
-@node Statements,Subprograms,Expressions and Names,Top
-@anchor{gnat-style statements}@anchor{b}
-@chapter Statements
-
-
-@menu
-* Simple and Compound Statements:: 
-* If Statements:: 
-* Case Statements:: 
-* Loop Statements:: 
-* Block Statements:: 
-
-@end menu
-
-@node Simple and Compound Statements,If Statements,,Statements
-@anchor{gnat-style simple-and-compound-statements}@anchor{c}
-@section Simple and Compound Statements
-
-
-
-@itemize *
-
-@item 
-Use only one statement or label per line.
-
-@item 
-A longer sequence_of_statements may be divided in logical
-groups or separated from surrounding code using a blank line.
-@end itemize
-
-@node If Statements,Case Statements,Simple and Compound Statements,Statements
-@anchor{gnat-style if-statements}@anchor{d}
-@section If Statements
-
-
-
-@itemize *
-
-@item 
-When the @code{if}, @code{elsif} or @code{else} keywords fit on the
-same line with the condition and the @code{then} keyword, then the
-statement is formatted as follows:
-
-@geindex Alignment (in an if statement)
-
-@example
-if condition then
-   ...
-elsif condition then
-   ...
-else
-   ...
-end if;
-@end example
-
-When the above layout is not possible, @code{then} should be aligned
-with @code{if}, and conditions should preferably be split before an
-@code{and} or @code{or} keyword a follows:
-
-@example
-if long_condition_that_has_to_be_split
-  and then continued_on_the_next_line
-then
-   ...
-end if;
-@end example
-
-The @code{elsif}, @code{else} and @code{end if} always line up with
-the @code{if} keyword.  The preferred location for splitting the line
-is before @code{and} or @code{or}.  The continuation of a condition is
-indented with two spaces or as many as needed to make nesting clear.
-As an exception, if conditions are closely related either of the
-following is allowed:
-
-@example
-if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
-     or else
-   x = asldkjhalkdsjfhhfd
-     or else
-   x = asdfadsfadsf
-then
-  ...
-end if;
-
-if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
-   x = asldkjhalkdsjfhhfd                         or else
-   x = asdfadsfadsf
-then
-  ...
-end if;
-@end example
-
-@item 
-Conditions should use short-circuit forms ( @code{and then},
-@code{or else} ), except when the operands are boolean variables
-or boolean constants.
-
-@geindex Short-circuit forms
-
-@item 
-Complex conditions in @code{if} statements are indented two characters:
-
-@geindex Indentation (in if statements)
-
-@example
-if this_complex_condition
-  and then that_other_one
-  and then one_last_one
-then
-   ...
-end if;
-@end example
-
-There are some cases where complex conditionals can be laid out
-in manners that do not follow these rules to preserve better
-parallelism between branches, e.g.
-
-@example
-if xyz.abc (gef) = 'c'
-     or else
-   xyz.abc (gef) = 'x'
-then
-   ...
-end if;
-@end example
-
-@item 
-Every @code{if} block is preceded and followed by a blank line, except
-where it begins or ends a sequence_of_statements.
-
-@geindex Blank lines (in an if statement)
-
-@example
-A := 5;
-
-if A = 5 then
-   null;
-end if;
-
-A := 6;
-@end example
-@end itemize
-
-@node Case Statements,Loop Statements,If Statements,Statements
-@anchor{gnat-style case-statements}@anchor{e}
-@section Case Statements
-
-
-
-@itemize *
-
-@item 
-Layout is as below.  For long @code{case} statements, the extra indentation
-can be saved by aligning the @code{when} clauses with the opening @code{case}.
-
-@example
-case expression is
-   when condition =>
-      ...
-   when condition =>
-      ...
-end case;
-@end example
-@end itemize
-
-@node Loop Statements,Block Statements,Case Statements,Statements
-@anchor{gnat-style loop-statements}@anchor{f}
-@section Loop Statements
-
-
-
-@itemize *
-
-@item 
-When possible, have @code{for} or @code{while} on one line with the
-condition and the @code{loop} keyword.
-
-@example
-for J in S'Range loop
-   ...
-end loop;
-@end example
-
-If the condition is too long, split the condition (see ‘If
-statements’ above) and align @code{loop} with the @code{for} or
-@code{while} keyword.
-
-@geindex Alignment (in a loop statement)
-
-@example
-while long_condition_that_has_to_be_split
-  and then continued_on_the_next_line
-loop
-   ...
-end loop;
-@end example
-
-If the loop_statement has an identifier, it is laid out as follows:
-
-@example
-Outer : while not condition loop
-   ...
-end Outer;
-@end example
-@end itemize
-
-@node Block Statements,,Loop Statements,Statements
-@anchor{gnat-style block-statements}@anchor{10}
-@section Block Statements
-
-
-
-@itemize *
-
-@item 
-The @code{declare} (optional), @code{begin} and @code{end} words
-are aligned, except when the block_statement is named.  There
-is a blank line before the @code{begin} keyword:
-
-@geindex Alignment (in a block statement)
-
-@example
-Some_Block : declare
-   ...
-
-begin
-   ...
-end Some_Block;
-@end example
-@end itemize
-
-@node Subprograms,Packages and Visibility Rules,Statements,Top
-@anchor{gnat-style subprograms}@anchor{11}
-@chapter Subprograms
-
-
-@menu
-* Subprogram Declarations:: 
-* Subprogram Bodies:: 
-
-@end menu
-
-@node Subprogram Declarations,Subprogram Bodies,,Subprograms
-@anchor{gnat-style subprogram-declarations}@anchor{12}
-@section Subprogram Declarations
-
-
-
-@itemize *
-
-@item 
-Do not write the @code{in} for parameters.
-
-@example
-function Length (S : String) return Integer;
-@end example
-
-@item 
-When the declaration line for a procedure or a function is too long to fit
-the entire declaration (including the keyword procedure or function) on a
-single line, then fold it, putting a single parameter on a line, aligning
-the colons, as in:
-
-@example
-procedure Set_Heading
-  (Source : String;
-   Count  : Natural;
-   Pad    : Character := Space;
-   Fill   : Boolean   := True);
-@end example
-
-In the case of a function, if the entire spec does not fit on one line, then
-the return may appear after the last parameter, as in:
-
-@example
-function Head
-  (Source : String;
-   Count  : Natural;
-   Pad    : Character := Space) return String;
-@end example
-
-Or it may appear on its own as a separate line. This form is preferred when
-putting the return on the same line as the last parameter would result in
-an overlong line. The return type may optionally be aligned with the types
-of the parameters (usually we do this aligning if it results only in a small
-number of extra spaces, and otherwise we don’t attempt to align). So two
-alternative forms for the above spec are:
-
-@example
-function Head
-  (Source : String;
-   Count  : Natural;
-   Pad    : Character := Space)
-   return   String;
-
-function Head
-  (Source : String;
-   Count  : Natural;
-   Pad    : Character := Space)
-   return String;
-@end example
-@end itemize
-
-@node Subprogram Bodies,,Subprogram Declarations,Subprograms
-@anchor{gnat-style subprogram-bodies}@anchor{13}
-@section Subprogram Bodies
-
-
-
-@itemize *
-
-@item 
-Function and procedure bodies should usually be sorted alphabetically. Do
-not attempt to sort them in some logical order by functionality. For a
-sequence of subprogram specs, a general alphabetical sorting is also
-usually appropriate, but occasionally it makes sense to group by major
-function, with appropriate headers.
-
-@item 
-All subprograms have a header giving the function name, with the following
-format:
-
-@example
------------------
--- My_Function --
------------------
-
-procedure My_Function is
-begin
-  ...
-end My_Function;
-@end example
-
-Note that the name in the header is preceded by a single space,
-not two spaces as for other comments. These headers are used on
-nested subprograms as well as outer level subprograms. They may
-also be used as headers for sections of comments, or collections
-of declarations that are related.
-
-@item 
-Every subprogram body must have a preceding subprogram_declaration,
-which includes proper client documentation so that you do not need to
-read the subprogram body in order to understand what the subprogram does and
-how to call it. All subprograms should be documented, without exceptions.
-
-@geindex Blank lines (in subprogram bodies)
-
-@item 
-A sequence of declarations may optionally be separated from the following
-begin by a blank line.  Just as we optionally allow blank lines in general
-between declarations, this blank line should be present only if it improves
-readability. Generally we avoid this blank line if the declarative part is
-small (one or two lines) and the body has no blank lines, and we include it
-if the declarative part is long or if the body has blank lines.
-
-@item 
-If the declarations in a subprogram contain at least one nested
-subprogram body, then just before the @code{begin} of the enclosing
-subprogram, there is a comment line and a blank line:
-
-@example
---  Start of processing for Enclosing_Subprogram
-
-begin
-  ...
-end Enclosing_Subprogram;
-@end example
-
-@item 
-When nested subprograms are present, variables that are referenced by any
-nested subprogram should precede the nested subprogram specs. For variables
-that are not referenced by nested procedures, the declarations can either also
-be before any of the nested subprogram specs (this is the old style, more
-generally used). Or then can come just before the begin, with a header. The
-following example shows the two possible styles:
-
-@example
-procedure Style1 is
-   Var_Referenced_In_Nested      : Integer;
-   Var_Referenced_Only_In_Style1 : Integer;
-
-   proc Nested;
-   --  Comments ...
-
-   ------------
-   -- Nested --
-   ------------
-
-   procedure Nested is
-   begin
-      ...
-   end Nested;
-
---  Start of processing for Style1
-
-begin
-   ...
-end Style1;
-
-procedure Style2 is
-   Var_Referenced_In_Nested : Integer;
-
-   proc Nested;
-   --  Comments ...
-
-   ------------
-   -- Nested --
-   ------------
-
-   procedure Nested is
-   begin
-      ...
-   end Nested;
-
-   --  Local variables
-
-   Var_Referenced_Only_In_Style2 : Integer;
-
---  Start of processing for Style2
-
-begin
-   ...
-end Style2;
-@end example
-
-For new code, we generally prefer Style2, but we do not insist on
-modifying all legacy occurrences of Style1, which is still much
-more common in the sources.
-@end itemize
-
-@node Packages and Visibility Rules,Program Structure and Compilation Issues,Subprograms,Top
-@anchor{gnat-style packages-and-visibility-rules}@anchor{14}
-@chapter Packages and Visibility Rules
-
-
-
-@itemize *
-
-@item 
-All program units and subprograms have their name at the end:
-
-@example
-package P is
-   ...
-end P;
-@end example
-
-@item 
-We will use the style of @code{use} -ing @code{with} -ed packages, with
-the context clauses looking like:
-
-@geindex use clauses
-
-@example
-with A; use A;
-with B; use B;
-@end example
-
-@item 
-Names declared in the visible part of packages should be
-unique, to prevent name clashes when the packages are @code{use} d.
-
-@geindex Name clash avoidance
-
-@example
-package Entity is
-   type Entity_Kind is ...;
-   ...
-end Entity;
-@end example
-
-@item 
-After the file header comment, the context clause and unit specification
-should be the first thing in a program_unit.
-
-@item 
-Preelaborate, Pure and Elaborate_Body pragmas should be added right after the
-package name, indented an extra level and using the parameterless form:
-
-@example
-package Preelaborate_Package is
-   pragma Preelaborate;
-   ...
-end Preelaborate_Package;
-@end example
-@end itemize
-
-@node Program Structure and Compilation Issues,Index,Packages and Visibility Rules,Top
-@anchor{gnat-style program-structure-and-compilation-issues}@anchor{15}
-@chapter Program Structure and Compilation Issues
-
-
-
-@itemize *
-
-@item 
-Every GNAT source file must be compiled with the @code{-gnatg}
-switch to check the coding style.
-(Note that you should look at
-style.adb to see the lexical rules enforced by @code{-gnatg} ).
-
-@geindex -gnatg option (to gcc)
-
-@geindex style.adb file
-
-@item 
-Each source file should contain only one compilation unit.
-
-@item 
-Filenames should be 8 or fewer characters, followed by the @code{.adb}
-extension for a body or @code{.ads} for a spec.
-
-@geindex File name length
-
-@item 
-Unit names should be distinct when ‘krunch’ed to 8 characters
-(see krunch.ads) and the filenames should match the unit name,
-except that they are all lower case.
-
-@geindex krunch.ads file
-@end itemize
-
-@menu
-* GNU Free Documentation License:: 
-
-@end menu
-
-@node GNU Free Documentation License,,,Program Structure and Compilation Issues
-@anchor{share/gnu_free_documentation_license doc}@anchor{16}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{17}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{18}
-@section GNU Free Documentation License
-
-
-Version 1.3, 3 November 2008
-
-Copyright  2000, 2001, 2002, 2007, 2008  Free Software Foundation, Inc
-@indicateurl{https://fsf.org/}
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-
-`Preamble'
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document “free” in the sense of freedom: to
-assure everyone the effective freedom to copy and redistribute it,
-with or without modifying it, either commercially or noncommercially.
-Secondarily, this License preserves for the author and publisher a way
-to get credit for their work, while not being considered responsible
-for modifications made by others.
-
-This License is a kind of “copyleft”, which means that derivative
-works of the document must themselves be free in the same sense.  It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does.  But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book.  We recommend this License
-principally for works whose purpose is instruction or reference.
-
-`1. APPLICABILITY AND DEFINITIONS'
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License.  Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein.  The `Document', below,
-refers to any such manual or work.  Any member of the public is a
-licensee, and is addressed as “`you'”.  You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-A “`Modified Version'” of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A “`Secondary Section'” is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document’s overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject.  (Thus, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.)  The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The “`Invariant Sections'” are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License.  If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant.  The Document may contain zero
-Invariant Sections.  If the Document does not identify any Invariant
-Sections then there are none.
-
-The “`Cover Texts'” are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License.  A Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A “`Transparent'” copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters.  A copy made in an otherwise Transparent file
-format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text.  A copy that is not “Transparent” is called `Opaque'.
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML, PostScript or PDF designed for human modification.  Examples of
-transparent image formats include PNG, XCF and JPG.  Opaque formats
-include proprietary formats that can be read and edited only by
-proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated HTML, PostScript or PDF produced by some word
-processors for output purposes only.
-
-The “`Title Page'” means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page.  For works in
-formats which do not have any title page as such, “Title Page” means
-the text near the most prominent appearance of the work’s title,
-preceding the beginning of the body of the text.
-
-The “`publisher'” means any person or entity that distributes
-copies of the Document to the public.
-
-A section “`Entitled XYZ'” means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language.  (Here XYZ stands for a
-specific section name mentioned below, such as “`Acknowledgements'”,
-“`Dedications'”, “`Endorsements'”, or “`History'”.)
-To “`Preserve the Title'”
-of such a section when you modify the Document means that it remains a
-section “Entitled XYZ” according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document.  These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-
-`2. VERBATIM COPYING'
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License.  You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute.  However, you may accept
-compensation in exchange for copies.  If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
-`3. COPYING IN QUANTITY'
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) of the Document, numbering more than 100, and the
-Document’s license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover.  Both covers must also clearly and legibly identify
-you as the publisher of these copies.  The front cover must present
-the full title with all words of the title equally prominent and
-visible.  You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-If you use the latter option, you must take reasonably prudent steps,
-when you begin distribution of Opaque copies in quantity, to ensure
-that this Transparent copy will remain thus accessible at the stated
-location until at least one year after the last time you distribute an
-Opaque copy (directly or through your agents or retailers) of that
-edition to the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
-`4. MODIFICATIONS'
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it.  In addition, you must do these things in the Modified Version:
-
-
-@enumerate A
-
-@item 
-Use in the Title Page (and on the covers, if any) a title distinct
-from that of the Document, and from those of previous versions
-(which should, if there were any, be listed in the History section
-of the Document).  You may use the same title as a previous version
-if the original publisher of that version gives permission.
-
-@item 
-List on the Title Page, as authors, one or more persons or entities
-responsible for authorship of the modifications in the Modified
-Version, together with at least five of the principal authors of the
-Document (all of its principal authors, if it has fewer than five),
-unless they release you from this requirement.
-
-@item 
-State on the Title page the name of the publisher of the
-Modified Version, as the publisher.
-
-@item 
-Preserve all the copyright notices of the Document.
-
-@item 
-Add an appropriate copyright notice for your modifications
-adjacent to the other copyright notices.
-
-@item 
-Include, immediately after the copyright notices, a license notice
-giving the public permission to use the Modified Version under the
-terms of this License, in the form shown in the Addendum below.
-
-@item 
-Preserve in that license notice the full lists of Invariant Sections
-and required Cover Texts given in the Document’s license notice.
-
-@item 
-Include an unaltered copy of this License.
-
-@item 
-Preserve the section Entitled “History”, Preserve its Title, and add
-to it an item stating at least the title, year, new authors, and
-publisher of the Modified Version as given on the Title Page.  If
-there is no section Entitled “History” in the Document, create one
-stating the title, year, authors, and publisher of the Document as
-given on its Title Page, then add an item describing the Modified
-Version as stated in the previous sentence.
-
-@item 
-Preserve the network location, if any, given in the Document for
-public access to a Transparent copy of the Document, and likewise
-the network locations given in the Document for previous versions
-it was based on.  These may be placed in the “History” section.
-You may omit a network location for a work that was published at
-least four years before the Document itself, or if the original
-publisher of the version it refers to gives permission.
-
-@item 
-For any section Entitled “Acknowledgements” or “Dedications”,
-Preserve the Title of the section, and preserve in the section all
-the substance and tone of each of the contributor acknowledgements
-and/or dedications given therein.
-
-@item 
-Preserve all the Invariant Sections of the Document,
-unaltered in their text and in their titles.  Section numbers
-or the equivalent are not considered part of the section titles.
-
-@item 
-Delete any section Entitled “Endorsements”.  Such a section
-may not be included in the Modified Version.
-
-@item 
-Do not retitle any existing section to be Entitled “Endorsements”
-or to conflict in title with any Invariant Section.
-
-@item 
-Preserve any Warranty Disclaimers.
-@end enumerate
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant.  To do this, add their titles to the
-list of Invariant Sections in the Modified Version’s license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section Entitled “Endorsements”, provided it contains
-nothing but endorsements of your Modified Version by various
-parties—for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version.  Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity.  If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
-`5. COMBINING DOCUMENTS'
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice, and that you preserve all their Warranty Disclaimers.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy.  If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled “History”
-in the various original documents, forming one section Entitled
-“History”; likewise combine any sections Entitled “Acknowledgements”,
-and any sections Entitled “Dedications”.  You must delete all sections
-Entitled “Endorsements”.
-
-`6. COLLECTIONS OF DOCUMENTS'
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
-`7. AGGREGATION WITH INDEPENDENT WORKS'
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, is called an “aggregate” if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation’s users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which are not themselves
-derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one half of
-the entire aggregate, the Document’s Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-
-`8. TRANSLATION'
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections.  You may include a
-translation of this License, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers.  In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled “Acknowledgements”,
-“Dedications”, or “History”, the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-
-`9. TERMINATION'
-
-You may not copy, modify, sublicense, or distribute the Document
-except as expressly provided under this License.  Any attempt
-otherwise to copy, modify, sublicense, or distribute it is void, and
-will automatically terminate your rights under this License.
-
-However, if you cease all violation of this License, then your license
-from a particular copyright holder is reinstated (a) provisionally,
-unless and until the copyright holder explicitly and finally
-terminates your license, and (b) permanently, if the copyright holder
-fails to notify you of the violation by some reasonable means prior to
-60 days after the cessation.
-
-Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, receipt of a copy of some or all of the same material does
-not give you any rights to use it.
-
-`10. FUTURE REVISIONS OF THIS LICENSE'
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time.  Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.  See
-@indicateurl{https://www.gnu.org/copyleft/}.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License “or any later version” applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation.  If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.  If the Document
-specifies that a proxy can decide which future versions of this
-License can be used, that proxy’s public statement of acceptance of a
-version permanently authorizes you to choose that version for the
-Document.
-
-`11. RELICENSING'
-
-“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
-World Wide Web server that publishes copyrightable works and also
-provides prominent facilities for anybody to edit those works.  A
-public wiki that anybody can edit is an example of such a server.  A
-“Massive Multiauthor Collaboration” (or “MMC”) contained in the
-site means any set of copyrightable works thus published on the MMC
-site.
-
-“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
-license published by Creative Commons Corporation, a not-for-profit
-corporation with a principal place of business in San Francisco,
-California, as well as future copyleft versions of that license
-published by that same organization.
-
-“Incorporate” means to publish or republish a Document, in whole or
-in part, as part of another Document.
-
-An MMC is “eligible for relicensing” if it is licensed under this
-License, and if all works that were first published under this License
-somewhere other than this MMC, and subsequently incorporated in whole
-or in part into the MMC, (1) had no cover texts or invariant sections,
-and (2) were thus incorporated prior to November 1, 2008.
-
-The operator of an MMC Site may republish an MMC contained in the site
-under CC-BY-SA on the same site at any time before August 1, 2009,
-provided the MMC is eligible for relicensing.
-
-`ADDENDUM: How to use this License for your documents'
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
-@quotation
-
-Copyright © YEAR  YOUR NAME.
-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, no Front-Cover Texts, and no Back-Cover Texts.
-A copy of the license is included in the section entitled “GNU
-Free Documentation License”.
-@end quotation
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the “with … Texts.” line with this:
-
-@quotation
-
-with the Invariant Sections being LIST THEIR TITLES, with the
-Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-@end quotation
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
-@node Index,,Program Structure and Compilation Issues,Top
-@unnumbered Index
-
-
-@printindex ge
-
-
-@c %**end of body
-@bye

diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
deleted file mode 100644 (file)
index fbd8bb8..0000000
--- a/gcc/ada/gnat_rm.texi
+++ /dev/null
@@ -1,30385 +0,0 @@
-\input texinfo   @c -*-texinfo-*-
-@c %**start of header
-@setfilename gnat_rm.info
-@documentencoding UTF-8
-@ifinfo
-@*Generated by Sphinx 5.2.3.@*
-@end ifinfo
-@settitle GNAT Reference Manual
-@defindex ge
-@paragraphindent 0
-@exampleindent 4
-@finalout
-@dircategory GNU Ada Tools 
-@direntry
-* gnat_rm: (gnat_rm.info). gnat_rm
-@end direntry
-
-@c %**end of header
-
-@copying
-@quotation
-GNAT Reference Manual , Oct 27, 2022
-
-AdaCore
-
-Copyright @copyright{} 2008-2022, Free Software Foundation
-@end quotation
-
-@end copying
-
-@titlepage
-@title GNAT Reference Manual
-@insertcopying
-@end titlepage
-@contents
-
-@c %** start of user preamble
-
-@c %** end of user preamble
-
-@ifnottex
-@node Top
-@top GNAT Reference Manual
-@insertcopying
-@end ifnottex
-
-@c %**start of body
-@anchor{gnat_rm doc}@anchor{0}
-`GNAT, The GNU Ada Development Environment'
-
-
-@include gcc-common.texi
-GCC version @value{version-GCC}@*
-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{1,,GNU Free Documentation License}.
-
-@menu
-* About This Guide:: 
-* Implementation Defined Pragmas:: 
-* Implementation Defined Aspects:: 
-* Implementation Defined Attributes:: 
-* Standard and Implementation Defined Restrictions:: 
-* Implementation Advice:: 
-* Implementation Defined Characteristics:: 
-* Intrinsic Subprograms:: 
-* Representation Clauses and Pragmas:: 
-* Standard Library Routines:: 
-* The Implementation of Standard I/O:: 
-* The GNAT Library:: 
-* Interfacing to Other Languages:: 
-* Specialized Needs Annexes:: 
-* Implementation of Specific Ada Features:: 
-* Implementation of Ada 2012 Features:: 
-* Security Hardening Features:: 
-* Obsolescent Features:: 
-* Compatibility and Porting Guide:: 
-* GNU Free Documentation License:: 
-* Index:: 
-
-@detailmenu
- --- The Detailed Node Listing ---
-
-About This Guide
-
-* What This Reference Manual Contains:: 
-* Conventions:: 
-* Related Information:: 
-
-Implementation Defined Pragmas
-
-* Pragma Abort_Defer:: 
-* Pragma Abstract_State:: 
-* Pragma Ada_83:: 
-* Pragma Ada_95:: 
-* Pragma Ada_05:: 
-* Pragma Ada_2005:: 
-* Pragma Ada_12:: 
-* Pragma Ada_2012:: 
-* Pragma Ada_2022:: 
-* Pragma Aggregate_Individually_Assign:: 
-* Pragma Allow_Integer_Address:: 
-* Pragma Annotate:: 
-* Pragma Assert:: 
-* Pragma Assert_And_Cut:: 
-* Pragma Assertion_Policy:: 
-* Pragma Assume:: 
-* Pragma Assume_No_Invalid_Values:: 
-* Pragma Async_Readers:: 
-* Pragma Async_Writers:: 
-* Pragma Attribute_Definition:: 
-* Pragma C_Pass_By_Copy:: 
-* Pragma Check:: 
-* Pragma Check_Float_Overflow:: 
-* Pragma Check_Name:: 
-* Pragma Check_Policy:: 
-* Pragma Comment:: 
-* Pragma Common_Object:: 
-* Pragma Compile_Time_Error:: 
-* Pragma Compile_Time_Warning:: 
-* Pragma Complete_Representation:: 
-* Pragma Complex_Representation:: 
-* Pragma Component_Alignment:: 
-* Pragma Constant_After_Elaboration:: 
-* Pragma Contract_Cases:: 
-* Pragma Convention_Identifier:: 
-* Pragma CPP_Class:: 
-* Pragma CPP_Constructor:: 
-* Pragma CPP_Virtual:: 
-* Pragma CPP_Vtable:: 
-* Pragma CPU:: 
-* Pragma Deadline_Floor:: 
-* Pragma Default_Initial_Condition:: 
-* Pragma Debug:: 
-* Pragma Debug_Policy:: 
-* Pragma Default_Scalar_Storage_Order:: 
-* Pragma Default_Storage_Pool:: 
-* Pragma Depends:: 
-* Pragma Detect_Blocking:: 
-* Pragma Disable_Atomic_Synchronization:: 
-* Pragma Dispatching_Domain:: 
-* Pragma Effective_Reads:: 
-* Pragma Effective_Writes:: 
-* Pragma Elaboration_Checks:: 
-* Pragma Eliminate:: 
-* Pragma Enable_Atomic_Synchronization:: 
-* Pragma Export_Function:: 
-* Pragma Export_Object:: 
-* Pragma Export_Procedure:: 
-* Pragma Export_Valued_Procedure:: 
-* Pragma Extend_System:: 
-* Pragma Extensions_Allowed:: 
-* Pragma Extensions_Visible:: 
-* Pragma External:: 
-* Pragma External_Name_Casing:: 
-* Pragma Fast_Math:: 
-* Pragma Favor_Top_Level:: 
-* Pragma Finalize_Storage_Only:: 
-* Pragma Float_Representation:: 
-* Pragma Ghost:: 
-* Pragma Global:: 
-* Pragma Ident:: 
-* Pragma Ignore_Pragma:: 
-* Pragma Implementation_Defined:: 
-* Pragma Implemented:: 
-* Pragma Implicit_Packing:: 
-* Pragma Import_Function:: 
-* Pragma Import_Object:: 
-* Pragma Import_Procedure:: 
-* Pragma Import_Valued_Procedure:: 
-* Pragma Independent:: 
-* Pragma Independent_Components:: 
-* Pragma Initial_Condition:: 
-* Pragma Initialize_Scalars:: 
-* Pragma Initializes:: 
-* Pragma Inline_Always:: 
-* Pragma Inline_Generic:: 
-* Pragma Interface:: 
-* Pragma Interface_Name:: 
-* Pragma Interrupt_Handler:: 
-* Pragma Interrupt_State:: 
-* Pragma Invariant:: 
-* Pragma Keep_Names:: 
-* Pragma License:: 
-* Pragma Link_With:: 
-* Pragma Linker_Alias:: 
-* Pragma Linker_Constructor:: 
-* Pragma Linker_Destructor:: 
-* Pragma Linker_Section:: 
-* Pragma Lock_Free:: 
-* Pragma Loop_Invariant:: 
-* Pragma Loop_Optimize:: 
-* Pragma Loop_Variant:: 
-* Pragma Machine_Attribute:: 
-* Pragma Main:: 
-* Pragma Main_Storage:: 
-* Pragma Max_Queue_Length:: 
-* Pragma No_Body:: 
-* Pragma No_Caching:: 
-* Pragma No_Component_Reordering:: 
-* Pragma No_Elaboration_Code_All:: 
-* Pragma No_Heap_Finalization:: 
-* Pragma No_Inline:: 
-* Pragma No_Return:: 
-* Pragma No_Strict_Aliasing:: 
-* Pragma No_Tagged_Streams:: 
-* Pragma Normalize_Scalars:: 
-* Pragma Obsolescent:: 
-* Pragma Optimize_Alignment:: 
-* Pragma Ordered:: 
-* Pragma Overflow_Mode:: 
-* Pragma Overriding_Renamings:: 
-* Pragma Partition_Elaboration_Policy:: 
-* Pragma Part_Of:: 
-* Pragma Passive:: 
-* Pragma Persistent_BSS:: 
-* Pragma Post:: 
-* Pragma Postcondition:: 
-* Pragma Post_Class:: 
-* Pragma Pre:: 
-* Pragma Precondition:: 
-* Pragma Predicate:: 
-* Pragma Predicate_Failure:: 
-* Pragma Preelaborable_Initialization:: 
-* Pragma Prefix_Exception_Messages:: 
-* Pragma Pre_Class:: 
-* Pragma Priority_Specific_Dispatching:: 
-* Pragma Profile:: 
-* Pragma Profile_Warnings:: 
-* Pragma Propagate_Exceptions:: 
-* Pragma Provide_Shift_Operators:: 
-* Pragma Psect_Object:: 
-* Pragma Pure_Function:: 
-* Pragma Rational:: 
-* Pragma Ravenscar:: 
-* Pragma Refined_Depends:: 
-* Pragma Refined_Global:: 
-* Pragma Refined_Post:: 
-* Pragma Refined_State:: 
-* Pragma Relative_Deadline:: 
-* Pragma Remote_Access_Type:: 
-* Pragma Rename_Pragma:: 
-* Pragma Restricted_Run_Time:: 
-* Pragma Restriction_Warnings:: 
-* Pragma Reviewable:: 
-* Pragma Secondary_Stack_Size:: 
-* Pragma Share_Generic:: 
-* Pragma Shared:: 
-* Pragma Short_Circuit_And_Or:: 
-* Pragma Short_Descriptors:: 
-* Pragma Simple_Storage_Pool_Type:: 
-* Pragma Source_File_Name:: 
-* Pragma Source_File_Name_Project:: 
-* Pragma Source_Reference:: 
-* Pragma SPARK_Mode:: 
-* Pragma Static_Elaboration_Desired:: 
-* Pragma Stream_Convert:: 
-* Pragma Style_Checks:: 
-* Pragma Subtitle:: 
-* Pragma Suppress:: 
-* Pragma Suppress_All:: 
-* Pragma Suppress_Debug_Info:: 
-* Pragma Suppress_Exception_Locations:: 
-* Pragma Suppress_Initialization:: 
-* Pragma Task_Name:: 
-* Pragma Task_Storage:: 
-* Pragma Test_Case:: 
-* Pragma Thread_Local_Storage:: 
-* Pragma Time_Slice:: 
-* Pragma Title:: 
-* Pragma Type_Invariant:: 
-* Pragma Type_Invariant_Class:: 
-* Pragma Unchecked_Union:: 
-* Pragma Unevaluated_Use_Of_Old:: 
-* Pragma Unimplemented_Unit:: 
-* Pragma Universal_Aliasing:: 
-* Pragma Unmodified:: 
-* Pragma Unreferenced:: 
-* Pragma Unreferenced_Objects:: 
-* Pragma Unreserve_All_Interrupts:: 
-* Pragma Unsuppress:: 
-* Pragma Use_VADS_Size:: 
-* Pragma Unused:: 
-* Pragma Validity_Checks:: 
-* Pragma Volatile:: 
-* Pragma Volatile_Full_Access:: 
-* Pragma Volatile_Function:: 
-* Pragma Warning_As_Error:: 
-* Pragma Warnings:: 
-* Pragma Weak_External:: 
-* Pragma Wide_Character_Encoding:: 
-
-Implementation Defined Aspects
-
-* Aspect Abstract_State:: 
-* Aspect Annotate:: 
-* Aspect Async_Readers:: 
-* Aspect Async_Writers:: 
-* Aspect Constant_After_Elaboration:: 
-* Aspect Contract_Cases:: 
-* Aspect Depends:: 
-* Aspect Default_Initial_Condition:: 
-* Aspect Dimension:: 
-* Aspect Dimension_System:: 
-* Aspect Disable_Controlled:: 
-* Aspect Effective_Reads:: 
-* Aspect Effective_Writes:: 
-* Aspect Extensions_Visible:: 
-* Aspect Favor_Top_Level:: 
-* Aspect Ghost:: 
-* Aspect Global:: 
-* Aspect Initial_Condition:: 
-* Aspect Initializes:: 
-* Aspect Inline_Always:: 
-* Aspect Invariant:: 
-* Aspect Invariant’Class:: 
-* Aspect Iterable:: 
-* Aspect Linker_Section:: 
-* Aspect Lock_Free:: 
-* Aspect Max_Queue_Length:: 
-* Aspect No_Caching:: 
-* Aspect No_Elaboration_Code_All:: 
-* Aspect No_Inline:: 
-* Aspect No_Tagged_Streams:: 
-* Aspect No_Task_Parts:: 
-* Aspect Object_Size:: 
-* Aspect Obsolescent:: 
-* Aspect Part_Of:: 
-* Aspect Persistent_BSS:: 
-* Aspect Predicate:: 
-* Aspect Pure_Function:: 
-* Aspect Refined_Depends:: 
-* Aspect Refined_Global:: 
-* Aspect Refined_Post:: 
-* Aspect Refined_State:: 
-* Aspect Relaxed_Initialization:: 
-* Aspect Remote_Access_Type:: 
-* Aspect Secondary_Stack_Size:: 
-* Aspect Scalar_Storage_Order:: 
-* Aspect Shared:: 
-* Aspect Simple_Storage_Pool:: 
-* Aspect Simple_Storage_Pool_Type:: 
-* Aspect SPARK_Mode:: 
-* Aspect Suppress_Debug_Info:: 
-* Aspect Suppress_Initialization:: 
-* Aspect Test_Case:: 
-* Aspect Thread_Local_Storage:: 
-* Aspect Universal_Aliasing:: 
-* Aspect Unmodified:: 
-* Aspect Unreferenced:: 
-* Aspect Unreferenced_Objects:: 
-* Aspect Value_Size:: 
-* Aspect Volatile_Full_Access:: 
-* Aspect Volatile_Function:: 
-* Aspect Warnings:: 
-
-Implementation Defined Attributes
-
-* Attribute Abort_Signal:: 
-* Attribute Address_Size:: 
-* Attribute Asm_Input:: 
-* Attribute Asm_Output:: 
-* Attribute Atomic_Always_Lock_Free:: 
-* Attribute Bit:: 
-* Attribute Bit_Position:: 
-* Attribute Code_Address:: 
-* Attribute Compiler_Version:: 
-* Attribute Constrained:: 
-* Attribute Default_Bit_Order:: 
-* Attribute Default_Scalar_Storage_Order:: 
-* Attribute Deref:: 
-* Attribute Descriptor_Size:: 
-* Attribute Elaborated:: 
-* Attribute Elab_Body:: 
-* Attribute Elab_Spec:: 
-* Attribute Elab_Subp_Body:: 
-* Attribute Emax:: 
-* Attribute Enabled:: 
-* Attribute Enum_Rep:: 
-* Attribute Enum_Val:: 
-* Attribute Epsilon:: 
-* Attribute Fast_Math:: 
-* Attribute Finalization_Size:: 
-* Attribute Fixed_Value:: 
-* Attribute From_Any:: 
-* Attribute Has_Access_Values:: 
-* Attribute Has_Discriminants:: 
-* Attribute Has_Tagged_Values:: 
-* Attribute Img:: 
-* Attribute Initialized:: 
-* Attribute Integer_Value:: 
-* Attribute Invalid_Value:: 
-* Attribute Iterable:: 
-* Attribute Large:: 
-* Attribute Library_Level:: 
-* Attribute Loop_Entry:: 
-* Attribute Machine_Size:: 
-* Attribute Mantissa:: 
-* Attribute Maximum_Alignment:: 
-* Attribute Max_Integer_Size:: 
-* Attribute Mechanism_Code:: 
-* Attribute Null_Parameter:: 
-* Attribute Object_Size:: 
-* Attribute Old:: 
-* Attribute Passed_By_Reference:: 
-* Attribute Pool_Address:: 
-* Attribute Range_Length:: 
-* Attribute Restriction_Set:: 
-* Attribute Result:: 
-* Attribute Safe_Emax:: 
-* Attribute Safe_Large:: 
-* Attribute Safe_Small:: 
-* Attribute Scalar_Storage_Order:: 
-* Attribute Simple_Storage_Pool:: 
-* Attribute Small:: 
-* Attribute Small_Denominator:: 
-* Attribute Small_Numerator:: 
-* Attribute Storage_Unit:: 
-* Attribute Stub_Type:: 
-* Attribute System_Allocator_Alignment:: 
-* Attribute Target_Name:: 
-* Attribute To_Address:: 
-* Attribute To_Any:: 
-* Attribute Type_Class:: 
-* Attribute Type_Key:: 
-* Attribute TypeCode:: 
-* Attribute Unconstrained_Array:: 
-* Attribute Universal_Literal_String:: 
-* Attribute Unrestricted_Access:: 
-* Attribute Update:: 
-* Attribute Valid_Value:: 
-* Attribute Valid_Scalars:: 
-* Attribute VADS_Size:: 
-* Attribute Value_Size:: 
-* Attribute Wchar_T_Size:: 
-* Attribute Word_Size:: 
-
-Standard and Implementation Defined Restrictions
-
-* Partition-Wide Restrictions:: 
-* Program Unit Level Restrictions:: 
-
-Partition-Wide Restrictions
-
-* Immediate_Reclamation:: 
-* Max_Asynchronous_Select_Nesting:: 
-* Max_Entry_Queue_Length:: 
-* Max_Protected_Entries:: 
-* Max_Select_Alternatives:: 
-* Max_Storage_At_Blocking:: 
-* Max_Task_Entries:: 
-* Max_Tasks:: 
-* No_Abort_Statements:: 
-* No_Access_Parameter_Allocators:: 
-* No_Access_Subprograms:: 
-* No_Allocators:: 
-* No_Anonymous_Allocators:: 
-* No_Asynchronous_Control:: 
-* No_Calendar:: 
-* No_Coextensions:: 
-* No_Default_Initialization:: 
-* No_Delay:: 
-* No_Dependence:: 
-* No_Direct_Boolean_Operators:: 
-* No_Dispatch:: 
-* No_Dispatching_Calls:: 
-* No_Dynamic_Attachment:: 
-* No_Dynamic_Priorities:: 
-* No_Entry_Calls_In_Elaboration_Code:: 
-* No_Enumeration_Maps:: 
-* No_Exception_Handlers:: 
-* No_Exception_Propagation:: 
-* No_Exception_Registration:: 
-* No_Exceptions:: 
-* No_Finalization:: 
-* No_Fixed_Point:: 
-* No_Floating_Point:: 
-* No_Implicit_Conditionals:: 
-* No_Implicit_Dynamic_Code:: 
-* No_Implicit_Heap_Allocations:: 
-* No_Implicit_Protected_Object_Allocations:: 
-* No_Implicit_Task_Allocations:: 
-* No_Initialize_Scalars:: 
-* No_IO:: 
-* No_Local_Allocators:: 
-* No_Local_Protected_Objects:: 
-* No_Local_Tagged_Types:: 
-* No_Local_Timing_Events:: 
-* No_Long_Long_Integers:: 
-* No_Multiple_Elaboration:: 
-* No_Nested_Finalization:: 
-* No_Protected_Type_Allocators:: 
-* No_Protected_Types:: 
-* No_Recursion:: 
-* No_Reentrancy:: 
-* No_Relative_Delay:: 
-* No_Requeue_Statements:: 
-* No_Secondary_Stack:: 
-* No_Select_Statements:: 
-* No_Specific_Termination_Handlers:: 
-* No_Specification_of_Aspect:: 
-* No_Standard_Allocators_After_Elaboration:: 
-* No_Standard_Storage_Pools:: 
-* No_Stream_Optimizations:: 
-* No_Streams:: 
-* No_Tagged_Type_Registration:: 
-* No_Task_Allocators:: 
-* No_Task_At_Interrupt_Priority:: 
-* No_Task_Attributes_Package:: 
-* No_Task_Hierarchy:: 
-* No_Task_Termination:: 
-* No_Tasking:: 
-* No_Terminate_Alternatives:: 
-* No_Unchecked_Access:: 
-* No_Unchecked_Conversion:: 
-* No_Unchecked_Deallocation:: 
-* No_Use_Of_Entity:: 
-* Pure_Barriers:: 
-* Simple_Barriers:: 
-* Static_Priorities:: 
-* Static_Storage_Size:: 
-
-Program Unit Level Restrictions
-
-* No_Elaboration_Code:: 
-* No_Dynamic_Accessibility_Checks:: 
-* No_Dynamic_Sized_Objects:: 
-* No_Entry_Queue:: 
-* No_Implementation_Aspect_Specifications:: 
-* No_Implementation_Attributes:: 
-* No_Implementation_Identifiers:: 
-* No_Implementation_Pragmas:: 
-* No_Implementation_Restrictions:: 
-* No_Implementation_Units:: 
-* No_Implicit_Aliasing:: 
-* No_Implicit_Loops:: 
-* No_Obsolescent_Features:: 
-* No_Wide_Characters:: 
-* Static_Dispatch_Tables:: 
-* SPARK_05:: 
-
-Implementation Advice
-
-* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 
-* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 
-* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 
-* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 
-* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 
-* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 
-* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 
-* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 
-* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 
-* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 
-* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 
-* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. 
-* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 
-* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 
-* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 
-* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 
-* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 
-* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 
-* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 
-* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 
-* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 
-* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 
-* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 
-* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 
-* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 
-* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 
-* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 
-* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 
-* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 
-* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 
-* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 
-* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. 
-* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 
-* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 
-* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 
-* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 
-* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 
-* RM A.18; Containers: RM A 18 Containers. 
-* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 
-* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 
-* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 
-* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 
-* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 
-* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 
-* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 
-* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 
-* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 
-* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 
-* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 
-* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 
-* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 
-* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 
-* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 
-* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 
-* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 
-* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 
-* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 
-* RM F(7); COBOL Support: RM F 7 COBOL Support. 
-* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 
-* RM G; Numerics: RM G Numerics. 
-* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 
-* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 
-* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 
-* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 
-* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 
-
-Intrinsic Subprograms
-
-* Intrinsic Operators:: 
-* Compilation_ISO_Date:: 
-* Compilation_Date:: 
-* Compilation_Time:: 
-* Enclosing_Entity:: 
-* Exception_Information:: 
-* Exception_Message:: 
-* Exception_Name:: 
-* File:: 
-* Line:: 
-* Shifts and Rotates:: 
-* Source_Location:: 
-
-Representation Clauses and Pragmas
-
-* Alignment Clauses:: 
-* Size Clauses:: 
-* Storage_Size Clauses:: 
-* Size of Variant Record Objects:: 
-* Biased Representation:: 
-* Value_Size and Object_Size Clauses:: 
-* Component_Size Clauses:: 
-* Bit_Order Clauses:: 
-* Effect of Bit_Order on Byte Ordering:: 
-* Pragma Pack for Arrays:: 
-* Pragma Pack for Records:: 
-* Record Representation Clauses:: 
-* Handling of Records with Holes:: 
-* Enumeration Clauses:: 
-* Address Clauses:: 
-* Use of Address Clauses for Memory-Mapped I/O:: 
-* Effect of Convention on Representation:: 
-* Conventions and Anonymous Access Types:: 
-* Determining the Representations chosen by GNAT:: 
-
-The Implementation of Standard I/O
-
-* Standard I/O Packages:: 
-* FORM Strings:: 
-* Direct_IO:: 
-* Sequential_IO:: 
-* Text_IO:: 
-* Wide_Text_IO:: 
-* Wide_Wide_Text_IO:: 
-* Stream_IO:: 
-* Text Translation:: 
-* Shared Files:: 
-* Filenames encoding:: 
-* File content encoding:: 
-* Open Modes:: 
-* Operations on C Streams:: 
-* Interfacing to C Streams:: 
-
-Text_IO
-
-* Stream Pointer Positioning:: 
-* Reading and Writing Non-Regular Files:: 
-* Get_Immediate:: 
-* Treating Text_IO Files as Streams:: 
-* Text_IO Extensions:: 
-* Text_IO Facilities for Unbounded Strings:: 
-
-Wide_Text_IO
-
-* Stream Pointer Positioning: Stream Pointer Positioning<2>. 
-* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 
-
-Wide_Wide_Text_IO
-
-* Stream Pointer Positioning: Stream Pointer Positioning<3>. 
-* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 
-
-The GNAT Library
-
-* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 
-* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 
-* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 
-* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 
-* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 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. 
-* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 
-* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 
-* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 
-* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 
-* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 
-* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 
-* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 
-* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): 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 a-swuwti ads. 
-* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 
-* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. 
-* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 
-* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 
-* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 
-* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 
-* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 
-* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): 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 a-ztcstr ads. 
-* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 
-* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 
-* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 
-* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 
-* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 
-* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 
-* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 
-* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 
-* GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. 
-* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 
-* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. 
-* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 
-* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 
-* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 
-* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 
-* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 
-* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 
-* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 
-* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 
-* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 
-* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 
-* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 
-* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 
-* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 
-* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 
-* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 
-* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 
-* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 
-* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 
-* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 
-* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 
-* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 
-* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 
-* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 
-* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 
-* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 
-* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 
-* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 
-* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 
-* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 
-* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 
-* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. 
-* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 
-* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 
-* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 
-* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 
-* GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. 
-* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 
-* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 
-* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 
-* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 
-* GNAT.IO (g-io.ads): GNAT IO g-io ads. 
-* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 
-* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 
-* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 
-* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 
-* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 
-* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 
-* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 
-* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 
-* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 
-* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 
-* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 
-* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 
-* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 
-* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 
-* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 
-* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 
-* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 
-* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 
-* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 
-* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 
-* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 
-* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 
-* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 
-* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 
-* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 
-* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 
-* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 
-* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 
-* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 
-* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 
-* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 
-* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 
-* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 
-* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 
-* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 
-* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 
-* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 
-* GNAT.Table (g-table.ads): GNAT Table g-table ads. 
-* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 
-* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 
-* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 
-* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 
-* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 
-* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 
-* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 
-* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 
-* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 
-* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 
-* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 
-* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 
-* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 
-* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 
-* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 
-* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 
-* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 
-* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 
-* System.Assertions (s-assert.ads): System Assertions s-assert ads. 
-* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 
-* System.Memory (s-memory.ads): System Memory s-memory ads. 
-* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 
-* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 
-* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 
-* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 
-* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 
-* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 
-* System.Rident (s-rident.ads): System Rident s-rident ads. 
-* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 
-* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 
-* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 
-* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 
-
-Interfacing to Other Languages
-
-* Interfacing to C:: 
-* Interfacing to C++:: 
-* Interfacing to COBOL:: 
-* Interfacing to Fortran:: 
-* Interfacing to non-GNAT Ada code:: 
-
-Implementation of Specific Ada Features
-
-* Machine Code Insertions:: 
-* GNAT Implementation of Tasking:: 
-* GNAT Implementation of Shared Passive Packages:: 
-* Code Generation for Array Aggregates:: 
-* The Size of Discriminated Records with Default Discriminants:: 
-* Image Values For Nonscalar Types:: 
-* Strict Conformance to the Ada Reference Manual:: 
-
-GNAT Implementation of Tasking
-
-* Mapping Ada Tasks onto the Underlying Kernel Threads:: 
-* Ensuring Compliance with the Real-Time Annex:: 
-* Support for Locking Policies:: 
-
-Code Generation for Array Aggregates
-
-* Static constant aggregates with static bounds:: 
-* Constant aggregates with unconstrained nominal types:: 
-* Aggregates with static bounds:: 
-* Aggregates with nonstatic bounds:: 
-* Aggregates in assignment statements:: 
-
-Security Hardening Features
-
-* Register Scrubbing:: 
-* Stack Scrubbing:: 
-* Hardened Conditionals:: 
-* Hardened Booleans:: 
-* Control Flow Redundancy:: 
-
-Obsolescent Features
-
-* pragma No_Run_Time:: 
-* pragma Ravenscar:: 
-* pragma Restricted_Run_Time:: 
-* pragma Task_Info:: 
-* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 
-
-Compatibility and Porting Guide
-
-* Writing Portable Fixed-Point Declarations:: 
-* Compatibility with Ada 83:: 
-* Compatibility between Ada 95 and Ada 2005:: 
-* Implementation-dependent characteristics:: 
-* Compatibility with Other Ada Systems:: 
-* Representation Clauses:: 
-* Compatibility with HP Ada 83:: 
-
-Compatibility with Ada 83
-
-* Legal Ada 83 programs that are illegal in Ada 95:: 
-* More deterministic semantics:: 
-* Changed semantics:: 
-* Other language compatibility issues:: 
-
-Implementation-dependent characteristics
-
-* Implementation-defined pragmas:: 
-* Implementation-defined attributes:: 
-* Libraries:: 
-* Elaboration order:: 
-* Target-specific aspects:: 
-
-@end detailmenu
-@end menu
-
-@node About This Guide,Implementation Defined Pragmas,Top,Top
-@anchor{gnat_rm/about_this_guide doc}@anchor{2}@anchor{gnat_rm/about_this_guide about-this-guide}@anchor{3}@anchor{gnat_rm/about_this_guide gnat-reference-manual}@anchor{4}@anchor{gnat_rm/about_this_guide id1}@anchor{5}
-@chapter About This Guide
-
-
-
-This manual contains useful information in writing programs using the
-GNAT compiler.  It includes information on implementation dependent
-characteristics of GNAT, including all the information required by
-Annex M of the Ada language standard.
-
-GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
-invoked in Ada 83 compatibility mode.
-By default, GNAT assumes Ada 2012,
-but you can override with a compiler switch
-to explicitly specify the language version.
-(Please refer to the `GNAT User’s Guide' for details on these switches.)
-Throughout this manual, references to ‘Ada’ without a year suffix
-apply to all the Ada versions of the language.
-
-Ada is designed to be highly portable.
-In general, a program will have the same effect even when compiled by
-different compilers on different platforms.
-However, since Ada is designed to be used in a
-wide variety of applications, it also contains a number of system
-dependent features to be used in interfacing to the external world.
-
-@geindex Implementation-dependent features
-
-@geindex Portability
-
-Note: Any program that makes use of implementation-dependent features
-may be non-portable.  You should follow good programming practice and
-isolate and clearly document any sections of your program that make use
-of these features in a non-portable manner.
-
-@menu
-* What This Reference Manual Contains:: 
-* Conventions:: 
-* Related Information:: 
-
-@end menu
-
-@node What This Reference Manual Contains,Conventions,,About This Guide
-@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6}
-@section What This Reference Manual Contains
-
-
-This reference manual contains the following chapters:
-
-
-@itemize *
-
-@item 
-@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent
-pragmas, which can be used to extend and enhance the functionality of the
-compiler.
-
-@item 
-@ref{8,,Implementation Defined Attributes}, lists GNAT
-implementation-dependent attributes, which can be used to extend and
-enhance the functionality of the compiler.
-
-@item 
-@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT
-implementation-dependent restrictions, which can be used to extend and
-enhance the functionality of the compiler.
-
-@item 
-@ref{a,,Implementation Advice}, provides information on generally
-desirable behavior which are not requirements that all compilers must
-follow since it cannot be provided on all systems, or which may be
-undesirable on some systems.
-
-@item 
-@ref{b,,Implementation Defined Characteristics}, provides a guide to
-minimizing implementation dependent features.
-
-@item 
-@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms
-implemented by GNAT, and how they can be imported into user
-application programs.
-
-@item 
-@ref{d,,Representation Clauses and Pragmas}, describes in detail the
-way that GNAT represents data, and in particular the exact set
-of representation clauses and pragmas that is accepted.
-
-@item 
-@ref{e,,Standard Library Routines}, provides a listing of packages and a
-brief description of the functionality that is provided by Ada’s
-extensive set of standard library routines as implemented by GNAT.
-
-@item 
-@ref{f,,The Implementation of Standard I/O}, details how the GNAT
-implementation of the input-output facilities.
-
-@item 
-@ref{10,,The GNAT Library}, is a catalog of packages that complement
-the Ada predefined library.
-
-@item 
-@ref{11,,Interfacing to Other Languages}, describes how programs
-written in Ada using GNAT can be interfaced to other programming
-languages.
-
-@item 
-@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all
-of the specialized needs annexes.
-
-@item 
-@ref{13,,Implementation of Specific Ada Features}, discusses issues related
-to GNAT’s implementation of machine code insertions, tasking, and several
-other features.
-
-@item 
-@ref{14,,Implementation of Ada 2012 Features}, describes the status of the
-GNAT implementation of the Ada 2012 language standard.
-
-@item 
-@ref{15,,Security Hardening Features} documents GNAT extensions aimed
-at security hardening.
-
-@item 
-@ref{16,,Obsolescent Features} documents implementation dependent features,
-including pragmas and attributes, which are considered obsolescent, since
-there are other preferred ways of achieving the same results. These
-obsolescent forms are retained for backwards compatibility.
-
-@item 
-@ref{17,,Compatibility and Porting Guide} presents some guidelines for
-developing portable Ada code, describes the compatibility issues that
-may arise between GNAT and other Ada compilation systems (including those
-for Ada 83), and shows how GNAT can expedite porting applications
-developed in other Ada environments.
-
-@item 
-@ref{1,,GNU Free Documentation License} contains the license for this document.
-@end itemize
-
-@geindex Ada 95 Language Reference Manual
-
-@geindex Ada 2005 Language Reference Manual
-
-This reference manual assumes a basic familiarity with the Ada 95 language, as
-described in the
-@cite{International Standard ANSI/ISO/IEC-8652:1995}.
-It does not require knowledge of the new features introduced by Ada 2005 or
-Ada 2012.
-All three reference manuals are included in the GNAT documentation
-package.
-
-@node Conventions,Related Information,What This Reference Manual Contains,About This Guide
-@anchor{gnat_rm/about_this_guide conventions}@anchor{18}
-@section Conventions
-
-
-@geindex Conventions
-@geindex typographical
-
-@geindex Typographical conventions
-
-Following are examples of the typographical and graphic conventions used
-in this guide:
-
-
-@itemize *
-
-@item 
-@code{Functions}, @code{utility program names}, @code{standard names},
-and @code{classes}.
-
-@item 
-@code{Option flags}
-
-@item 
-@code{File names}
-
-@item 
-@code{Variables}
-
-@item 
-`Emphasis'
-
-@item 
-[optional information or parameters]
-
-@item 
-Examples are described by text
-
-@example
-and then shown this way.
-@end example
-
-@item 
-Commands that are entered by the user are shown as preceded by a prompt string
-comprising the @code{$} character followed by a space.
-@end itemize
-
-@node Related Information,,Conventions,About This Guide
-@anchor{gnat_rm/about_this_guide related-information}@anchor{19}
-@section Related Information
-
-
-See the following documents for further information on GNAT:
-
-
-@itemize *
-
-@item 
-@cite{GNAT User’s Guide for Native Platforms},
-which provides information on how to use the
-GNAT development environment.
-
-@item 
-@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard.
-
-@item 
-@cite{Ada 95 Annotated Reference Manual}, which is an annotated version
-of the Ada 95 standard.  The annotations describe
-detailed aspects of the design decision, and in particular contain useful
-sections on Ada 83 compatibility.
-
-@item 
-@cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard.
-
-@item 
-@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version
-of the Ada 2005 standard.  The annotations describe
-detailed aspects of the design decision.
-
-@item 
-@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard.
-
-@item 
-@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms},
-which contains specific information on compatibility between GNAT and
-DEC Ada 83 systems.
-
-@item 
-@cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which
-describes in detail the pragmas and attributes provided by the DEC Ada 83
-compiler system.
-@end itemize
-
-@node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top
-@anchor{gnat_rm/implementation_defined_pragmas doc}@anchor{1a}@anchor{gnat_rm/implementation_defined_pragmas id1}@anchor{1b}@anchor{gnat_rm/implementation_defined_pragmas implementation-defined-pragmas}@anchor{7}
-@chapter Implementation Defined Pragmas
-
-
-Ada defines a set of pragmas that can be used to supply additional
-information to the compiler.  These language defined pragmas are
-implemented in GNAT and work as described in the Ada Reference Manual.
-
-In addition, Ada allows implementations to define additional pragmas
-whose meaning is defined by the implementation.  GNAT provides a number
-of these implementation-defined pragmas, which can be used to extend
-and enhance the functionality of the compiler.  This section of the GNAT
-Reference Manual describes these additional pragmas.
-
-Note that any program using these pragmas might not be portable to other
-compilers (although GNAT implements this set of pragmas on all
-platforms).  Therefore if portability to other compilers is an important
-consideration, the use of these pragmas should be minimized.
-
-@menu
-* Pragma Abort_Defer:: 
-* Pragma Abstract_State:: 
-* Pragma Ada_83:: 
-* Pragma Ada_95:: 
-* Pragma Ada_05:: 
-* Pragma Ada_2005:: 
-* Pragma Ada_12:: 
-* Pragma Ada_2012:: 
-* Pragma Ada_2022:: 
-* Pragma Aggregate_Individually_Assign:: 
-* Pragma Allow_Integer_Address:: 
-* Pragma Annotate:: 
-* Pragma Assert:: 
-* Pragma Assert_And_Cut:: 
-* Pragma Assertion_Policy:: 
-* Pragma Assume:: 
-* Pragma Assume_No_Invalid_Values:: 
-* Pragma Async_Readers:: 
-* Pragma Async_Writers:: 
-* Pragma Attribute_Definition:: 
-* Pragma C_Pass_By_Copy:: 
-* Pragma Check:: 
-* Pragma Check_Float_Overflow:: 
-* Pragma Check_Name:: 
-* Pragma Check_Policy:: 
-* Pragma Comment:: 
-* Pragma Common_Object:: 
-* Pragma Compile_Time_Error:: 
-* Pragma Compile_Time_Warning:: 
-* Pragma Complete_Representation:: 
-* Pragma Complex_Representation:: 
-* Pragma Component_Alignment:: 
-* Pragma Constant_After_Elaboration:: 
-* Pragma Contract_Cases:: 
-* Pragma Convention_Identifier:: 
-* Pragma CPP_Class:: 
-* Pragma CPP_Constructor:: 
-* Pragma CPP_Virtual:: 
-* Pragma CPP_Vtable:: 
-* Pragma CPU:: 
-* Pragma Deadline_Floor:: 
-* Pragma Default_Initial_Condition:: 
-* Pragma Debug:: 
-* Pragma Debug_Policy:: 
-* Pragma Default_Scalar_Storage_Order:: 
-* Pragma Default_Storage_Pool:: 
-* Pragma Depends:: 
-* Pragma Detect_Blocking:: 
-* Pragma Disable_Atomic_Synchronization:: 
-* Pragma Dispatching_Domain:: 
-* Pragma Effective_Reads:: 
-* Pragma Effective_Writes:: 
-* Pragma Elaboration_Checks:: 
-* Pragma Eliminate:: 
-* Pragma Enable_Atomic_Synchronization:: 
-* Pragma Export_Function:: 
-* Pragma Export_Object:: 
-* Pragma Export_Procedure:: 
-* Pragma Export_Valued_Procedure:: 
-* Pragma Extend_System:: 
-* Pragma Extensions_Allowed:: 
-* Pragma Extensions_Visible:: 
-* Pragma External:: 
-* Pragma External_Name_Casing:: 
-* Pragma Fast_Math:: 
-* Pragma Favor_Top_Level:: 
-* Pragma Finalize_Storage_Only:: 
-* Pragma Float_Representation:: 
-* Pragma Ghost:: 
-* Pragma Global:: 
-* Pragma Ident:: 
-* Pragma Ignore_Pragma:: 
-* Pragma Implementation_Defined:: 
-* Pragma Implemented:: 
-* Pragma Implicit_Packing:: 
-* Pragma Import_Function:: 
-* Pragma Import_Object:: 
-* Pragma Import_Procedure:: 
-* Pragma Import_Valued_Procedure:: 
-* Pragma Independent:: 
-* Pragma Independent_Components:: 
-* Pragma Initial_Condition:: 
-* Pragma Initialize_Scalars:: 
-* Pragma Initializes:: 
-* Pragma Inline_Always:: 
-* Pragma Inline_Generic:: 
-* Pragma Interface:: 
-* Pragma Interface_Name:: 
-* Pragma Interrupt_Handler:: 
-* Pragma Interrupt_State:: 
-* Pragma Invariant:: 
-* Pragma Keep_Names:: 
-* Pragma License:: 
-* Pragma Link_With:: 
-* Pragma Linker_Alias:: 
-* Pragma Linker_Constructor:: 
-* Pragma Linker_Destructor:: 
-* Pragma Linker_Section:: 
-* Pragma Lock_Free:: 
-* Pragma Loop_Invariant:: 
-* Pragma Loop_Optimize:: 
-* Pragma Loop_Variant:: 
-* Pragma Machine_Attribute:: 
-* Pragma Main:: 
-* Pragma Main_Storage:: 
-* Pragma Max_Queue_Length:: 
-* Pragma No_Body:: 
-* Pragma No_Caching:: 
-* Pragma No_Component_Reordering:: 
-* Pragma No_Elaboration_Code_All:: 
-* Pragma No_Heap_Finalization:: 
-* Pragma No_Inline:: 
-* Pragma No_Return:: 
-* Pragma No_Strict_Aliasing:: 
-* Pragma No_Tagged_Streams:: 
-* Pragma Normalize_Scalars:: 
-* Pragma Obsolescent:: 
-* Pragma Optimize_Alignment:: 
-* Pragma Ordered:: 
-* Pragma Overflow_Mode:: 
-* Pragma Overriding_Renamings:: 
-* Pragma Partition_Elaboration_Policy:: 
-* Pragma Part_Of:: 
-* Pragma Passive:: 
-* Pragma Persistent_BSS:: 
-* Pragma Post:: 
-* Pragma Postcondition:: 
-* Pragma Post_Class:: 
-* Pragma Pre:: 
-* Pragma Precondition:: 
-* Pragma Predicate:: 
-* Pragma Predicate_Failure:: 
-* Pragma Preelaborable_Initialization:: 
-* Pragma Prefix_Exception_Messages:: 
-* Pragma Pre_Class:: 
-* Pragma Priority_Specific_Dispatching:: 
-* Pragma Profile:: 
-* Pragma Profile_Warnings:: 
-* Pragma Propagate_Exceptions:: 
-* Pragma Provide_Shift_Operators:: 
-* Pragma Psect_Object:: 
-* Pragma Pure_Function:: 
-* Pragma Rational:: 
-* Pragma Ravenscar:: 
-* Pragma Refined_Depends:: 
-* Pragma Refined_Global:: 
-* Pragma Refined_Post:: 
-* Pragma Refined_State:: 
-* Pragma Relative_Deadline:: 
-* Pragma Remote_Access_Type:: 
-* Pragma Rename_Pragma:: 
-* Pragma Restricted_Run_Time:: 
-* Pragma Restriction_Warnings:: 
-* Pragma Reviewable:: 
-* Pragma Secondary_Stack_Size:: 
-* Pragma Share_Generic:: 
-* Pragma Shared:: 
-* Pragma Short_Circuit_And_Or:: 
-* Pragma Short_Descriptors:: 
-* Pragma Simple_Storage_Pool_Type:: 
-* Pragma Source_File_Name:: 
-* Pragma Source_File_Name_Project:: 
-* Pragma Source_Reference:: 
-* Pragma SPARK_Mode:: 
-* Pragma Static_Elaboration_Desired:: 
-* Pragma Stream_Convert:: 
-* Pragma Style_Checks:: 
-* Pragma Subtitle:: 
-* Pragma Suppress:: 
-* Pragma Suppress_All:: 
-* Pragma Suppress_Debug_Info:: 
-* Pragma Suppress_Exception_Locations:: 
-* Pragma Suppress_Initialization:: 
-* Pragma Task_Name:: 
-* Pragma Task_Storage:: 
-* Pragma Test_Case:: 
-* Pragma Thread_Local_Storage:: 
-* Pragma Time_Slice:: 
-* Pragma Title:: 
-* Pragma Type_Invariant:: 
-* Pragma Type_Invariant_Class:: 
-* Pragma Unchecked_Union:: 
-* Pragma Unevaluated_Use_Of_Old:: 
-* Pragma Unimplemented_Unit:: 
-* Pragma Universal_Aliasing:: 
-* Pragma Unmodified:: 
-* Pragma Unreferenced:: 
-* Pragma Unreferenced_Objects:: 
-* Pragma Unreserve_All_Interrupts:: 
-* Pragma Unsuppress:: 
-* Pragma Use_VADS_Size:: 
-* Pragma Unused:: 
-* Pragma Validity_Checks:: 
-* Pragma Volatile:: 
-* Pragma Volatile_Full_Access:: 
-* Pragma Volatile_Function:: 
-* Pragma Warning_As_Error:: 
-* Pragma Warnings:: 
-* Pragma Weak_External:: 
-* Pragma Wide_Character_Encoding:: 
-
-@end menu
-
-@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1c}
-@section Pragma Abort_Defer
-
-
-@geindex Deferring aborts
-
-Syntax:
-
-@example
-pragma Abort_Defer;
-@end example
-
-This pragma must appear at the start of the statement sequence of a
-handled sequence of statements (right after the @code{begin}).  It has
-the effect of deferring aborts for the sequence of statements (but not
-for the declarations or handlers, if any, associated with this statement
-sequence). This can also be useful for adding a polling point in Ada code,
-where asynchronous abort of tasks is checked when leaving the statement
-sequence, and is lighter than, for example, using @code{delay 0.0;}, since with
-zero-cost exception handling, propagating exceptions (implicitly used to
-implement task abort) cannot be done reliably in an asynchronous way.
-
-An example of usage would be:
-
-@example
---  Add a polling point to check for task aborts
-
-begin
-   pragma Abort_Defer;
-end;
-@end example
-
-@node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d}@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1e}
-@section Pragma Abstract_State
-
-
-Syntax:
-
-@example
-pragma Abstract_State (ABSTRACT_STATE_LIST);
-
-ABSTRACT_STATE_LIST ::=
-     null
-  |  STATE_NAME_WITH_OPTIONS
-  | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} )
-
-STATE_NAME_WITH_OPTIONS ::=
-     STATE_NAME
-  | (STATE_NAME with OPTION_LIST)
-
-OPTION_LIST ::= OPTION @{, OPTION@}
-
-OPTION ::=
-    SIMPLE_OPTION
-  | NAME_VALUE_OPTION
-
-SIMPLE_OPTION ::= Ghost | Synchronous
-
-NAME_VALUE_OPTION ::=
-    Part_Of => ABSTRACT_STATE
-  | External [=> EXTERNAL_PROPERTY_LIST]
-
-EXTERNAL_PROPERTY_LIST ::=
-     EXTERNAL_PROPERTY
-  | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} )
-
-EXTERNAL_PROPERTY ::=
-    Async_Readers    [=> static_boolean_EXPRESSION]
-  | Async_Writers    [=> static_boolean_EXPRESSION]
-  | Effective_Reads  [=> static_boolean_EXPRESSION]
-  | Effective_Writes [=> static_boolean_EXPRESSION]
-    others            => static_boolean_EXPRESSION
-
-STATE_NAME ::= defining_identifier
-
-ABSTRACT_STATE ::= name
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1f}
-@section Pragma Ada_83
-
-
-Syntax:
-
-@example
-pragma Ada_83;
-@end example
-
-A configuration pragma that establishes Ada 83 mode for the unit to
-which it applies, regardless of the mode set by the command line
-switches.  In Ada 83 mode, GNAT attempts to be as compatible with
-the syntax and semantics of Ada 83, as defined in the original Ada
-83 Reference Manual as possible.  In particular, the keywords added by Ada 95
-and Ada 2005 are not recognized, optional package bodies are allowed,
-and generics may name types with unknown discriminants without using
-the @code{(<>)} notation.  In addition, some but not all of the additional
-restrictions of Ada 83 are enforced.
-
-Ada 83 mode is intended for two purposes.  Firstly, it allows existing
-Ada 83 code to be compiled and adapted to GNAT with less effort.
-Secondly, it aids in keeping code backwards compatible with Ada 83.
-However, there is no guarantee that code that is processed correctly
-by GNAT in Ada 83 mode will in fact compile and execute with an Ada
-83 compiler, since GNAT does not enforce all the additional checks
-required by Ada 83.
-
-@node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{20}
-@section Pragma Ada_95
-
-
-Syntax:
-
-@example
-pragma Ada_95;
-@end example
-
-A configuration pragma that establishes Ada 95 mode for the unit to which
-it applies, regardless of the mode set by the command line switches.
-This mode is set automatically for the @code{Ada} and @code{System}
-packages and their children, so you need not specify it in these
-contexts.  This pragma is useful when writing a reusable component that
-itself uses Ada 95 features, but which is intended to be usable from
-either Ada 83 or Ada 95 programs.
-
-@node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{21}
-@section Pragma Ada_05
-
-
-Syntax:
-
-@example
-pragma Ada_05;
-pragma Ada_05 (local_NAME);
-@end example
-
-A configuration pragma that establishes Ada 2005 mode for the unit to which
-it applies, regardless of the mode set by the command line switches.
-This pragma is useful when writing a reusable component that
-itself uses Ada 2005 features, but which is intended to be usable from
-either Ada 83 or Ada 95 programs.
-
-The one argument form (which is not a configuration pragma)
-is used for managing the transition from
-Ada 95 to Ada 2005 in the run-time library. If an entity is marked
-as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95
-mode will generate a warning. In addition, in Ada_83 or Ada_95
-mode, a preference rule is established which does not choose
-such an entity unless it is unambiguously specified. This avoids
-extra subprograms marked this way from generating ambiguities in
-otherwise legal pre-Ada_2005 programs. The one argument form is
-intended for exclusive use in the GNAT run-time library.
-
-@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{22}
-@section Pragma Ada_2005
-
-
-Syntax:
-
-@example
-pragma Ada_2005;
-@end example
-
-This configuration pragma is a synonym for pragma Ada_05 and has the
-same syntax and effect.
-
-@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{23}
-@section Pragma Ada_12
-
-
-Syntax:
-
-@example
-pragma Ada_12;
-pragma Ada_12 (local_NAME);
-@end example
-
-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 @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
-Ada 83, Ada 95, or Ada 2005 programs.
-
-The one argument form, which is not a configuration pragma,
-is used for managing the transition from Ada
-2005 to Ada 2012 in the run-time library. If an entity is marked
-as Ada_2012 only, then referencing the entity in any pre-Ada_2012
-mode will generate a warning. In addition, in any pre-Ada_2012
-mode, a preference rule is established which does not choose
-such an entity unless it is unambiguously specified. This avoids
-extra subprograms marked this way from generating ambiguities in
-otherwise legal pre-Ada_2012 programs. The one argument form is
-intended for exclusive use in the GNAT run-time library.
-
-@node Pragma Ada_2012,Pragma Ada_2022,Pragma Ada_12,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{24}
-@section Pragma Ada_2012
-
-
-Syntax:
-
-@example
-pragma Ada_2012;
-@end example
-
-This configuration pragma is a synonym for pragma Ada_12 and has the
-same syntax and effect.
-
-@node Pragma Ada_2022,Pragma Aggregate_Individually_Assign,Pragma Ada_2012,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2022}@anchor{25}
-@section Pragma Ada_2022
-
-
-Syntax:
-
-@example
-pragma Ada_2022;
-pragma Ada_2022 (local_NAME);
-@end example
-
-A configuration pragma that establishes Ada 2022 mode for the unit to which
-it applies, regardless of the mode set by the command line switches.
-This mode is set automatically for the @code{Ada} and @code{System}
-packages and their children, so you need not specify it in these
-contexts.  This pragma is useful when writing a reusable component that
-itself uses Ada 2022 features, but which is intended to be usable from
-Ada 83, Ada 95, Ada 2005 or Ada 2012 programs.
-
-The one argument form, which is not a configuration pragma,
-is used for managing the transition from Ada
-2012 to Ada 2022 in the run-time library. If an entity is marked
-as Ada_2022 only, then referencing the entity in any pre-Ada_2022
-mode will generate a warning. In addition, in any pre-Ada_2012
-mode, a preference rule is established which does not choose
-such an entity unless it is unambiguously specified. This avoids
-extra subprograms marked this way from generating ambiguities in
-otherwise legal pre-Ada_2022 programs. The one argument form is
-intended for exclusive use in the GNAT run-time library.
-
-@node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2022,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{26}
-@section Pragma Aggregate_Individually_Assign
-
-
-Syntax:
-
-@example
-pragma Aggregate_Individually_Assign;
-@end example
-
-Where possible, GNAT will store the binary representation of a record aggregate
-in memory for space and performance reasons. This configuration pragma changes
-this behavior so that record aggregates are instead always converted into
-individual assignment statements.
-
-@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{27}
-@section Pragma Allow_Integer_Address
-
-
-Syntax:
-
-@example
-pragma Allow_Integer_Address;
-@end example
-
-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
-@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 @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:
-
-@example
-pragma Allow_Integer_Address;
-with System; use System;
-package AddrAsInt is
-   X : Integer;
-   Y : Integer;
-   for X'Address use 16#1240#;
-   for Y use at 16#3230#;
-   m : Address := 16#4000#;
-   n : constant Address := 4000;
-   p : constant Address := Address (X + Y);
-   v : Integer := y'Address;
-   w : constant Integer := Integer (Y'Address);
-   type R is new integer;
-   RR : R := 1000;
-   Z : Integer;
-   for Z'Address use RR;
-end AddrAsInt;
-@end example
-
-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
-in the two situations.
-
-@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{28}@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{29}
-@section Pragma Annotate
-
-
-Syntax:
-
-@example
-pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]);
-
-ARG ::= NAME | EXPRESSION
-@end example
-
-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
-can be either string literals or more generally expressions.
-String literals (and concatenations of string literals) are assumed to be
-either of type
-@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
-@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
-lines in the generated ALI file. For the format of these note lines, see
-the compiler source file lib-writ.ads. This pragma is intended for use by
-external tools, including ASIS. The use of pragma Annotate does not
-affect the compilation process in any way. This pragma may be used as
-a configuration pragma.
-
-@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{2a}
-@section Pragma Assert
-
-
-Syntax:
-
-@example
-pragma Assert (
-  boolean_EXPRESSION
-  [, string_EXPRESSION]);
-@end example
-
-The effect of this pragma depends on whether the corresponding command
-line switch is set to activate assertions.  The pragma expands into code
-equivalent to the following:
-
-@example
-if assertions-enabled then
-   if not boolean_EXPRESSION then
-      System.Assertions.Raise_Assert_Failure
-        (string_EXPRESSION);
-   end if;
-end if;
-@end example
-
-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 @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 @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 `-gnata' is
-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
-expression will not occur at run time).  (The expression is still
-analyzed at compile time, and may cause types to be frozen if they are
-mentioned here for the first time).
-
-If assertions are checked, then the given expression is tested, and if
-it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
-which results in the raising of @code{Assert_Failure} with the given message.
-
-You should generally avoid side effects in the expression arguments of
-this pragma, because these side effects will turn on and off with the
-setting of the assertions mode, resulting in assertions that have an
-effect on the program.  However, the expressions are analyzed for
-semantic correctness whether or not assertions are enabled, so turning
-assertions on and off cannot affect the legality of a program.
-
-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
-of Ada, and the DISABLE policy is an implementation-defined
-addition.
-
-@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2b}
-@section Pragma Assert_And_Cut
-
-
-Syntax:
-
-@example
-pragma Assert_And_Cut (
-  boolean_EXPRESSION
-  [, string_EXPRESSION]);
-@end example
-
-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
-given test expresion sums up all the work done so far in the
-subprogram, so that the rest of the subprogram can be verified
-(informally or formally) using only the entry preconditions,
-and the expression in this pragma. This allows dividing up
-a subprogram into sections for the purposes of testing or
-formal verification. The pragma also serves as useful
-documentation.
-
-@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2c}
-@section Pragma Assertion_Policy
-
-
-Syntax:
-
-@example
-pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE);
-
-pragma Assertion_Policy (
-    ASSERTION_KIND => POLICY_IDENTIFIER
- @{, ASSERTION_KIND => POLICY_IDENTIFIER@});
-
-ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND
-
-RM_ASSERTION_KIND ::= Assert                    |
-                      Static_Predicate          |
-                      Dynamic_Predicate         |
-                      Pre                       |
-                      Pre'Class                 |
-                      Post                      |
-                      Post'Class                |
-                      Type_Invariant            |
-                      Type_Invariant'Class      |
-                      Default_Initial_Condition
-
-ID_ASSERTION_KIND ::= Assertions           |
-                      Assert_And_Cut       |
-                      Assume               |
-                      Contract_Cases       |
-                      Debug                |
-                      Ghost                |
-                      Initial_Condition    |
-                      Invariant            |
-                      Invariant'Class      |
-                      Loop_Invariant       |
-                      Loop_Variant         |
-                      Postcondition        |
-                      Precondition         |
-                      Predicate            |
-                      Refined_Post         |
-                      Statement_Assertions |
-                      Subprogram_Variant
-
-POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible
-@end example
-
-This is a standard Ada 2012 pragma that is available as an
-implementation-defined pragma in earlier versions of Ada.
-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. @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 @code{CHECK}, then assertions are enabled, i.e.
-the corresponding pragma or aspect is activated.
-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 `-gnata' switch on the
-command line.
-If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default,
-however, if the `-gnatp' switch is specified all assertions are ignored.
-
-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 @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 @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{2d}
-@section Pragma Assume
-
-
-Syntax:
-
-@example
-pragma Assume (
-  boolean_EXPRESSION
-  [, string_EXPRESSION]);
-@end example
-
-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
-external environment. So you cannot expect to verify formally
-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
-@code{Long_Long_Integer} being at least 64. So we could write:
-
-@example
-pragma Assume (Long_Long_Integer'Size >= 64);
-@end example
-
-This assumption cannot be proved from the program itself,
-but it acts as a useful run-time check that the assumption
-is met, and documents the need to ensure that it is met by
-reference to information outside the program.
-
-@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2e}
-@section Pragma Assume_No_Invalid_Values
-
-
-@geindex Invalid representations
-
-@geindex Invalid values
-
-Syntax:
-
-@example
-pragma Assume_No_Invalid_Values (On | Off);
-@end example
-
-This is a configuration pragma that controls the assumptions made by the
-compiler about the occurrence of invalid representations (invalid values)
-in the code.
-
-The default behavior (corresponding to an Off argument for this pragma), is
-to assume that values may in general be invalid unless the compiler can
-prove they are valid. Consider the following example:
-
-@example
-V1 : Integer range 1 .. 10;
-V2 : Integer range 11 .. 20;
-...
-for J in V2 .. V1 loop
-   ...
-end loop;
-@end example
-
-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 @code{Assume_No_Invalid_Values (On)}
-is given, the compiler will assume that any occurrence of a variable
-other than in an explicit @code{'Valid} test always has a valid
-value, and the loop above will be optimized away.
-
-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
-with this pragma in effect is erroneous, so no guarantees can be made
-about its behavior.
-
-It is peculiar though permissible to use this pragma in conjunction
-with validity checking (-gnatVa). In such cases, accessing invalid
-values will generally give an exception, though formally the program
-is erroneous so there are no guarantees that this will always be the
-case, and it is recommended that these two options not be used together.
-
-@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2f}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{30}
-@section Pragma Async_Readers
-
-
-Syntax:
-
-@example
-pragma Async_Readers [ (static_boolean_EXPRESSION) ];
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{31}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{32}
-@section Pragma Async_Writers
-
-
-Syntax:
-
-@example
-pragma Async_Writers [ (static_boolean_EXPRESSION) ];
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{33}
-@section Pragma Attribute_Definition
-
-
-Syntax:
-
-@example
-pragma Attribute_Definition
-  ([Attribute  =>] ATTRIBUTE_DESIGNATOR,
-   [Entity     =>] LOCAL_NAME,
-   [Expression =>] EXPRESSION | NAME);
-@end example
-
-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 @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.
-
-@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{34}
-@section Pragma C_Pass_By_Copy
-
-
-@geindex Passing by copy
-
-Syntax:
-
-@example
-pragma C_Pass_By_Copy
-  ([Max_Size =>] static_integer_EXPRESSION);
-@end example
-
-Normally the default mechanism for passing C convention records to C
-convention subprograms is to pass them by reference, as suggested by RM
-B.3(69).  Use the configuration pragma @code{C_Pass_By_Copy} to change
-this default, by requiring that record formal parameters be passed by
-copy if all of the following conditions are met:
-
-
-@itemize *
-
-@item 
-The size of the record type does not exceed the value specified for
-@code{Max_Size}.
-
-@item 
-The record type has @code{Convention C}.
-
-@item 
-The formal parameter has this record type, and the subprogram has a
-foreign (non-Ada) convention.
-@end itemize
-
-If these conditions are met the argument is passed by copy; i.e., in a
-manner consistent with what C expects if the corresponding formal in the
-C prototype is a struct (rather than a pointer to a struct).
-
-You can also pass records by copy by specifying the convention
-@code{C_Pass_By_Copy} for the record type, or by using the extended
-@code{Import} and @code{Export} pragmas, which allow specification of
-passing mechanisms on a parameter by parameter basis.
-
-@node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{35}
-@section Pragma Check
-
-
-@geindex Assertions
-
-@geindex Named assertions
-
-Syntax:
-
-@example
-pragma Check (
-     [Name    =>] CHECK_KIND,
-     [Check   =>] Boolean_EXPRESSION
-  [, [Message =>] string_EXPRESSION] );
-
-CHECK_KIND ::= IDENTIFIER           |
-               Pre'Class            |
-               Post'Class           |
-               Type_Invariant'Class |
-               Invariant'Class
-@end example
-
-This pragma is similar to the predefined pragma @code{Assert} except that an
-extra identifier argument is present. In conjunction with pragma
-@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 `-gnata', which turns on
-all checks, or individually controlled using pragma @code{Check_Policy}.
-
-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 @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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{36}
-@section Pragma Check_Float_Overflow
-
-
-@geindex Floating-point overflow
-
-Syntax:
-
-@example
-pragma Check_Float_Overflow;
-@end example
-
-In Ada, the predefined floating-point types (@code{Short_Float},
-@code{Float}, @code{Long_Float}, @code{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.
-This implementation permission accommodates the notion
-of infinities in IEEE floating-point, and corresponds to the
-efficient execution mode on most machines. GNAT will not raise
-overflow exceptions on these machines; instead it will generate
-infinities and NaN’s as defined in the IEEE standard.
-
-Generating infinities, although efficient, is not always desirable.
-Often the preferable approach is to check for overflow, even at the
-(perhaps considerable) expense of run-time performance.
-This can be accomplished by defining your own constrained floating-point subtypes – i.e., by supplying explicit
-range constraints – and indeed such a subtype
-can have the same base range as its base type. For example:
-
-@example
-subtype My_Float is Float range Float'Range;
-@end example
-
-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 @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 @code{Constraint_Error}
-exception is raised if the result is out of range.
-
-This mode can also be set by use of the compiler
-switch `-gnateF'.
-
-@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{37}
-@section Pragma Check_Name
-
-
-@geindex Defining check names
-
-@geindex Check names
-@geindex defining
-
-Syntax:
-
-@example
-pragma Check_Name (check_name_IDENTIFIER);
-@end example
-
-This is a configuration pragma that defines a new implementation
-defined check name (unless IDENTIFIER matches one of the predefined
-check names, in which case the pragma has no effect). Check names
-are global to a partition, so if two or more configuration pragmas
-are present in a partition mentioning the same name, only one new
-check name is introduced.
-
-An implementation defined check name introduced with this pragma may
-be used in only three contexts: @code{pragma Suppress},
-@code{pragma Unsuppress},
-and as the prefix of a @code{Check_Name'Enabled} attribute reference. For
-any of these three cases, the check name must be visible. A check
-name is visible if it is in the configuration pragmas applying to
-the current unit, or if it appears at the start of any unit that
-is part of the dependency set of the current unit (e.g., units that
-are mentioned in @code{with} clauses).
-
-Check names introduced by this pragma are subject to control by compiler
-switches (in particular -gnatp) in the usual manner.
-
-@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{38}
-@section Pragma Check_Policy
-
-
-@geindex Controlling assertions
-
-@geindex Assertions
-@geindex control
-
-@geindex Check pragma control
-
-@geindex Named assertions
-
-Syntax:
-
-@example
-pragma Check_Policy
- ([Name   =>] CHECK_KIND,
-  [Policy =>] POLICY_IDENTIFIER);
-
-pragma Check_Policy (
-    CHECK_KIND => POLICY_IDENTIFIER
- @{, CHECK_KIND => POLICY_IDENTIFIER@});
-
-ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND
-
-CHECK_KIND ::= IDENTIFIER           |
-               Pre'Class            |
-               Post'Class           |
-               Type_Invariant'Class |
-               Invariant'Class
-
-The identifiers Name and Policy are not allowed as CHECK_KIND values. This
-avoids confusion between the two possible syntax forms for this pragma.
-
-POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE
-@end example
-
-This pragma is used to set the checking policy for assertions (specified
-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 @code{Suppress}).
-
-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 @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 @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 @code{Check}. For example, if the pragma:
-
-@example
-pragma Check_Policy (Critical_Error, OFF);
-@end example
-
-is given, then subsequent @code{Check} pragmas whose first argument is also
-@code{Critical_Error} will be disabled.
-
-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
-@code{Check_Policy} is given is @code{OFF} unless the compiler switch
-`-gnata' is given, which turns on all checks by default.
-
-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{39}
-@section Pragma Comment
-
-
-Syntax:
-
-@example
-pragma Comment (static_string_EXPRESSION);
-@end example
-
-This is almost identical in effect to pragma @code{Ident}.  It allows the
-placement of a comment into the object file and hence into the
-executable file if the operating system permits such usage.  The
-difference is that @code{Comment}, unlike @code{Ident}, has
-no limitations on placement of the pragma (it can be placed
-anywhere in the main source unit), and if more than one pragma
-is used, all comments are retained.
-
-@node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{3a}
-@section Pragma Common_Object
-
-
-Syntax:
-
-@example
-pragma Common_Object (
-     [Internal =>] LOCAL_NAME
-  [, [External =>] EXTERNAL_SYMBOL]
-  [, [Size     =>] EXTERNAL_SYMBOL] );
-
-EXTERNAL_SYMBOL ::=
-  IDENTIFIER
-| static_string_EXPRESSION
-@end example
-
-This pragma enables the shared use of variables stored in overlaid
-linker areas corresponding to the use of @code{COMMON}
-in Fortran.  The single
-object @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 @code{Size} argument
-is syntax checked in GNAT, but otherwise ignored.
-
-@code{Common_Object} is not supported on all platforms.  If no
-support is available, then the code generator will issue a message
-indicating that the necessary attribute for implementation of this
-pragma is not available.
-
-@node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas compile-time-error}@anchor{3b}@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3c}
-@section Pragma Compile_Time_Error
-
-
-Syntax:
-
-@example
-pragma Compile_Time_Error
-         (boolean_EXPRESSION, static_string_EXPRESSION);
-@end example
-
-This pragma can be used to generate additional compile time
-error messages. It
-is particularly useful in generics, where errors can be issued for
-specific problematic instantiations. The first parameter is a boolean
-expression. The pragma ensures that the value of an expression
-is known at compile time, and has the value False. The set of expressions
-whose values are known at compile time includes all static boolean
-expressions, and also other values which the compiler can determine
-at compile time (e.g., the size of a record type set by an explicit
-size representation clause, or the value of a variable which was
-initialized to a constant and is known not to have been modified).
-If these conditions are not met, an error message is generated using
-the value given as the second argument. This string value may contain
-embedded ASCII.LF characters to break the message into multiple lines.
-
-@node Pragma Compile_Time_Warning,Pragma Complete_Representation,Pragma Compile_Time_Error,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3d}
-@section Pragma Compile_Time_Warning
-
-
-Syntax:
-
-@example
-pragma Compile_Time_Warning
-         (boolean_EXPRESSION, static_string_EXPRESSION);
-@end example
-
-Same as pragma Compile_Time_Error, except a warning is issued instead
-of an error message. If switch `-gnatw_C' is used, a warning is only issued
-if the value of the expression is known to be True at compile time, not when
-the value of the expression is not known at compile time.
-Note that if this pragma is used in a package that
-is with’ed by a client, the client will get the warning even though it
-is issued by a with’ed package (normally warnings in with’ed units are
-suppressed, but this is a special exception to that rule).
-
-One typical use is within a generic where compile time known characteristics
-of formal parameters are tested, and warnings given appropriately. Another use
-with a first parameter of True is to warn a client about use of a package,
-for example that it is not fully implemented.
-
-In previous versions of the compiler, combining `-gnatwe' with
-Compile_Time_Warning resulted in a fatal error. Now the compiler always emits
-a warning. You can use @ref{3b,,Pragma Compile_Time_Error} to force the generation of
-an error.
-
-@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compile_Time_Warning,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3e}
-@section Pragma Complete_Representation
-
-
-Syntax:
-
-@example
-pragma Complete_Representation;
-@end example
-
-This pragma must appear immediately within a record representation
-clause. Typical placements are before the first component clause
-or after the last component clause. The effect is to give an error
-message if any component is missing a component clause. This pragma
-may be used to ensure that a record representation clause is
-complete, and that this invariant is maintained if fields are
-added to the record in the future.
-
-@node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{3f}
-@section Pragma Complex_Representation
-
-
-Syntax:
-
-@example
-pragma Complex_Representation
-        ([Entity =>] LOCAL_NAME);
-@end example
-
-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
-the code for this type not conforming to standard ABI (application
-binary interface) requirements for the handling of record types.  For
-example, in some environments, there is a requirement for passing
-records by pointer, and the use of this pragma may result in passing
-this type in floating-point registers.
-
-@node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{40}
-@section Pragma Component_Alignment
-
-
-@geindex Alignments of components
-
-@geindex Pragma Component_Alignment
-
-Syntax:
-
-@example
-pragma Component_Alignment (
-     [Form =>] ALIGNMENT_CHOICE
-  [, [Name =>] type_LOCAL_NAME]);
-
-ALIGNMENT_CHOICE ::=
-  Component_Size
-| Component_Size_4
-| Storage_Unit
-| Default
-@end example
-
-Specifies the alignment of components in array or record types.
-The meaning of the @code{Form} argument is as follows:
-
-@quotation
-
-@geindex Component_Size (in pragma Component_Alignment)
-@end quotation
-
-
-@table @asis
-
-@item `Component_Size'
-
-Aligns scalar components and subcomponents of the array or record type
-on boundaries appropriate to their inherent size (naturally
-aligned).  For example, 1-byte components are aligned on byte boundaries,
-2-byte integer components are aligned on 2-byte boundaries, 4-byte
-integer components are aligned on 4-byte boundaries and so on.  These
-alignment rules correspond to the normal rules for C compilers on all
-machines except the VAX.
-
-@geindex Component_Size_4 (in pragma Component_Alignment)
-
-@item `Component_Size_4'
-
-Naturally aligns components with a size of four or fewer
-bytes.  Components that are larger than 4 bytes are placed on the next
-4-byte boundary.
-
-@geindex Storage_Unit (in pragma Component_Alignment)
-
-@item `Storage_Unit'
-
-Specifies that array or record components are byte aligned, i.e.,
-aligned on boundaries determined by the value of the constant
-@code{System.Storage_Unit}.
-
-@geindex Default (in pragma Component_Alignment)
-
-@item `Default'
-
-Specifies that array or record components are aligned on default
-boundaries, appropriate to the underlying hardware or operating system or
-both. The @code{Default} choice is the same as @code{Component_Size} (natural
-alignment).
-@end table
-
-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
-@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 @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
-are declared within this declarative part, or within any nested scope
-within this declarative part.  In either case it specifies the alignment
-to be applied to any record or array type which has otherwise standard
-representation.
-
-If the alignment for a record or array type is not specified (using
-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
-@anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{41}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{42}
-@section Pragma Constant_After_Elaboration
-
-
-Syntax:
-
-@example
-pragma Constant_After_Elaboration [ (static_boolean_EXPRESSION) ];
-@end example
-
-For the semantics of this pragma, see the entry for aspect
-@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{43}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{44}
-@section Pragma Contract_Cases
-
-
-@geindex Contract cases
-
-Syntax:
-
-@example
-pragma Contract_Cases (CONTRACT_CASE @{, CONTRACT_CASE@});
-
-CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE
-
-CASE_GUARD ::= boolean_EXPRESSION | others
-
-CONSEQUENCE ::= boolean_EXPRESSION
-@end example
-
-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 @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
-cases
-
-@example
-pragma Contract_Cases (
-  Cond1 => Pred1,
-  Cond2 => Pred2);
-@end example
-
-are equivalent to
-
-@example
-C1 : constant Boolean := Cond1;  --  evaluated at subprogram entry
-C2 : constant Boolean := Cond2;  --  evaluated at subprogram entry
-pragma Precondition ((C1 and not C2) or (C2 and not C1));
-pragma Postcondition (if C1 then Pred1);
-pragma Postcondition (if C2 then Pred2);
-@end example
-
-The precondition ensures that one and only one of the case guards is
-satisfied on entry to the subprogram.
-The postcondition ensures that for the case guard that was True on entry,
-the corresponding consequence is True on exit. Other consequence expressions
-are not evaluated.
-
-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 @code{Contract_Cases} pragmas are
-identical to those described for preconditions and postconditions.
-
-The compiler checks that boolean expressions given in case guards and
-consequences are valid, where the rules for case guards are the same as
-the rule for an expression in @code{Precondition} and the rules for
-consequences 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 consequence expressions.
-The case guard 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:
-
-@example
-package Math_Functions is
-   ...
-   function Sqrt (Arg : Float) return Float;
-   pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0,
-                           Arg >= 100.0         => Sqrt'Result >= 10.0,
-                           others               => Sqrt'Result = 0.0));
-   ...
-end Math_Functions;
-@end example
-
-The meaning of contract cases is that only one case should apply at each
-call, as determined by the corresponding case guard evaluating to True,
-and that the consequence for this case should hold when the subprogram
-returns.
-
-@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{45}
-@section Pragma Convention_Identifier
-
-
-@geindex Conventions
-@geindex synonyms
-
-Syntax:
-
-@example
-pragma Convention_Identifier (
-         [Name =>]       IDENTIFIER,
-         [Convention =>] convention_IDENTIFIER);
-@end example
-
-This pragma provides a mechanism for supplying synonyms for existing
-convention identifiers. The @code{Name} identifier can subsequently
-be used as a synonym for the given convention in other pragmas (including
-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:
-
-@example
-pragma Convention_Identifier (Fortran77, Fortran);
-@end example
-
-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 @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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{46}
-@section Pragma CPP_Class
-
-
-@geindex Interfacing with C++
-
-Syntax:
-
-@example
-pragma CPP_Class ([Entity =>] LOCAL_NAME);
-@end example
-
-The argument denotes an entity in the current declarative region that is
-declared as a 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. If the C++ class has virtual primitives
-then the record must be declared as a tagged record type.
-
-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 @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{47,,Interfacing to C++} for related information.
-
-Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
-for backward compatibility but its functionality is available
-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{48}
-@section Pragma CPP_Constructor
-
-
-@geindex Interfacing with C++
-
-Syntax:
-
-@example
-pragma CPP_Constructor ([Entity =>] LOCAL_NAME
-  [, [External_Name =>] static_string_EXPRESSION ]
-  [, [Link_Name     =>] static_string_EXPRESSION ]);
-@end example
-
-This pragma identifies an imported function (imported in the usual way
-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 
-`function' @code{Fname} `return' T`
-
-@item 
-`function' @code{Fname} `return' T’Class
-
-@item 
-`function' @code{Fname} (…) `return' T`
-
-@item 
-`function' @code{Fname} (…) `return' T’Class
-@end itemize
-
-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 @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 @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{47,,Interfacing to C++} for more related information.
-
-Note: The use of functions returning class-wide types for constructors is
-currently obsolete. They are supported for backward compatibility. The
-use of functions returning the type T leave the Ada sources more clear
-because the imported C++ constructors always return an object of type T;
-that is, they never return an object whose type is a descendant of type T.
-
-@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{49}
-@section Pragma CPP_Virtual
-
-
-@geindex Interfacing to C++
-
-This pragma is now obsolete and, other than generating a warning if warnings
-on obsolescent features are enabled, is completely ignored.
-It is retained for compatibility
-purposes. It used to be required to ensure compatibility with C++, but
-is no longer required for that purpose because GNAT generates
-the same object layout as the G++ compiler by default.
-
-See @ref{47,,Interfacing to C++} for related information.
-
-@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4a}
-@section Pragma CPP_Vtable
-
-
-@geindex Interfacing with C++
-
-This pragma is now obsolete and, other than generating a warning if warnings
-on obsolescent features are enabled, is completely ignored.
-It used to be required to ensure compatibility with C++, but
-is no longer required for that purpose because GNAT generates
-the same object layout as the G++ compiler by default.
-
-See @ref{47,,Interfacing to C++} for related information.
-
-@node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4b}
-@section Pragma CPU
-
-
-Syntax:
-
-@example
-pragma CPU (EXPRESSION);
-@end example
-
-This pragma is standard in Ada 2012, but is available in all earlier
-versions of Ada as an implementation-defined pragma.
-See Ada 2012 Reference Manual for details.
-
-@node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4c}
-@section Pragma Deadline_Floor
-
-
-Syntax:
-
-@example
-pragma Deadline_Floor (time_span_EXPRESSION);
-@end example
-
-This pragma applies only to protected types and specifies the floor
-deadline inherited by a task when the task enters a protected object.
-It is effective only when the EDF scheduling policy is used.
-
-@node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4d}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{4e}
-@section Pragma Default_Initial_Condition
-
-
-Syntax:
-
-@example
-pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ];
-@end example
-
-For the semantics of this pragma, see the entry for aspect
-@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{4f}
-@section Pragma Debug
-
-
-Syntax:
-
-@example
-pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON);
-
-PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
-  PROCEDURE_NAME
-| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
-@end example
-
-The procedure call argument has the syntactic form of an expression, meeting
-the syntactic requirements for pragmas.
-
-If debug pragmas are not enabled or if the condition is present and evaluates
-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 @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 `-gnata'
-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{50}
-@section Pragma Debug_Policy
-
-
-Syntax:
-
-@example
-pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF);
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{51}
-@section Pragma Default_Scalar_Storage_Order
-
-
-@geindex Default_Scalar_Storage_Order
-
-@geindex Scalar_Storage_Order
-
-Syntax:
-
-@example
-pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First);
-@end example
-
-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
-spec or declarative part. In the latter case, it applies to all subsequent
-types declared within that package spec or declarative part.
-
-The following example shows the use of this pragma:
-
-@example
-pragma Default_Scalar_Storage_Order (High_Order_First);
-with System; use System;
-package DSSO1 is
-   type H1 is record
-      a : Integer;
-   end record;
-
-   type L2 is record
-      a : Integer;
-   end record;
-   for L2'Scalar_Storage_Order use Low_Order_First;
-
-   type L2a is new L2;
-
-   package Inner is
-      type H3 is record
-         a : Integer;
-      end record;
-
-      pragma Default_Scalar_Storage_Order (Low_Order_First);
-
-      type L4 is record
-         a : Integer;
-      end record;
-   end Inner;
-
-   type H4a is new Inner.L4;
-
-   type H5 is record
-      a : Integer;
-   end record;
-end DSSO1;
-@end example
-
-In this example record types with names starting with `L' have @cite{Low_Order_First} scalar
-storage order, and record types with names starting with `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
-configuration pragma file (as opposed to appearing explicitly at the start
-of a single unit), then the binder will require that all units in a partition
-be compiled in a similar manner, other than run-time units, which are not
-affected by this pragma. Note that the use of this form is discouraged because
-it may significantly degrade the run-time performance of the software, instead
-the default scalar storage order ought to be changed only on a local basis.
-
-@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{52}
-@section Pragma Default_Storage_Pool
-
-
-@geindex Default_Storage_Pool
-
-Syntax:
-
-@example
-pragma Default_Storage_Pool (storage_pool_NAME | null);
-@end example
-
-This pragma is standard in Ada 2012, but is available in all earlier
-versions of Ada as an implementation-defined pragma.
-See Ada 2012 Reference Manual for details.
-
-@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{53}@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{54}
-@section Pragma Depends
-
-
-Syntax:
-
-@example
-pragma Depends (DEPENDENCY_RELATION);
-
-DEPENDENCY_RELATION ::=
-     null
-  | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@})
-
-DEPENDENCY_CLAUSE ::=
-    OUTPUT_LIST =>[+] INPUT_LIST
-  | NULL_DEPENDENCY_CLAUSE
-
-NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST
-
-OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@})
-
-INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@})
-
-OUTPUT ::= NAME | FUNCTION_RESULT
-INPUT  ::= NAME
-
-where FUNCTION_RESULT is a function Result attribute_reference
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{55}
-@section Pragma Detect_Blocking
-
-
-Syntax:
-
-@example
-pragma Detect_Blocking;
-@end example
-
-This is a standard pragma in Ada 2005, that is available in all earlier
-versions of Ada as an implementation-defined pragma.
-
-This is a configuration pragma that forces the detection of potentially
-blocking operations within a protected operation, and to raise Program_Error
-if that happens.
-
-@node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{56}
-@section Pragma Disable_Atomic_Synchronization
-
-
-@geindex Atomic Synchronization
-
-Syntax:
-
-@example
-pragma Disable_Atomic_Synchronization [(Entity)];
-@end example
-
-Ada requires that accesses (reads or writes) of an atomic variable be
-regarded as synchronization points in the case of multiple tasks.
-Particularly in the case of multi-processors this may require special
-handling, e.g. the generation of memory barriers. This capability may
-be turned off using this pragma in cases where it is known not to be
-required.
-
-The placement and scope rules for this pragma are the same as those
-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 @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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{57}
-@section Pragma Dispatching_Domain
-
-
-Syntax:
-
-@example
-pragma Dispatching_Domain (EXPRESSION);
-@end example
-
-This pragma is standard in Ada 2012, but is available in all earlier
-versions of Ada as an implementation-defined pragma.
-See Ada 2012 Reference Manual for details.
-
-@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{58}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{59}
-@section Pragma Effective_Reads
-
-
-Syntax:
-
-@example
-pragma Effective_Reads [ (static_boolean_EXPRESSION) ];
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5a}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5b}
-@section Pragma Effective_Writes
-
-
-Syntax:
-
-@example
-pragma Effective_Writes [ (static_boolean_EXPRESSION) ];
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5c}
-@section Pragma Elaboration_Checks
-
-
-@geindex Elaboration control
-
-Syntax:
-
-@example
-pragma Elaboration_Checks (Dynamic | Static);
-@end example
-
-This is a configuration pragma which specifies the elaboration model to be
-used during compilation. For more information on the elaboration models of
-GNAT, consult the chapter on elaboration order handling in the `GNAT User’s
-Guide'.
-
-The pragma may appear in the following contexts:
-
-
-@itemize *
-
-@item 
-Configuration pragmas file
-
-@item 
-Prior to the context clauses of a compilation unit’s initial declaration
-@end itemize
-
-Any other placement of the pragma will result in a warning and the effects of
-the offending pragma will be ignored.
-
-If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in
-effect. If the pragma argument is @code{Static}, then the static elaboration model
-is in effect.
-
-@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5d}
-@section Pragma Eliminate
-
-
-@geindex Elimination of unused subprograms
-
-Syntax:
-
-@example
-pragma Eliminate (
-            [  Unit_Name       => ] IDENTIFIER | SELECTED_COMPONENT ,
-            [  Entity          => ] IDENTIFIER |
-                                    SELECTED_COMPONENT |
-                                    STRING_LITERAL
-            [, Source_Location =>   SOURCE_TRACE ] );
-
-        SOURCE_TRACE    ::= STRING_LITERAL
-@end example
-
-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 @code{U} is the unit specified by
-the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity}
-argument:
-
-
-@itemize *
-
-@item 
-@code{E} must be a subprogram that is explicitly declared either:
-
-
-@itemize *
-
-@item 
-Within @code{U}, or
-
-@item 
-Within a generic package that is instantiated in @code{U}, or
-
-@item 
-As an instance of generic subprogram instantiated in @code{U}.
-@end itemize
-
-Otherwise the pragma is ignored.
-
-@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
-@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 @code{Eliminate} pragmas invalid because their
-@code{Source_Location} argument values may get out of date.
-
-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{5e}
-@section Pragma Enable_Atomic_Synchronization
-
-
-@geindex Atomic Synchronization
-
-Syntax:
-
-@example
-pragma Enable_Atomic_Synchronization [(Entity)];
-@end example
-
-Ada requires that accesses (reads or writes) of an atomic variable be
-regarded as synchronization points in the case of multiple tasks.
-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
-@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 @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 @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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{5f}
-@section Pragma Export_Function
-
-
-@geindex Argument passing mechanisms
-
-Syntax:
-
-@example
-pragma Export_Function (
-     [Internal         =>] LOCAL_NAME
-  [, [External         =>] EXTERNAL_SYMBOL]
-  [, [Parameter_Types  =>] PARAMETER_TYPES]
-  [, [Result_Type      =>] result_SUBTYPE_MARK]
-  [, [Mechanism        =>] MECHANISM]
-  [, [Result_Mechanism =>] MECHANISM_NAME]);
-
-EXTERNAL_SYMBOL ::=
-  IDENTIFIER
-| static_string_EXPRESSION
-| ""
-
-PARAMETER_TYPES ::=
-  null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
-  subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
-  MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
-  [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::= Value | Reference
-@end example
-
-Use this pragma to make a function externally callable and optionally
-provide information on mechanisms to be used for passing parameter and
-result values.  We recommend, for the purposes of improving portability,
-this pragma always be used in conjunction with a separate pragma
-@code{Export}, which must precede the pragma @code{Export_Function}.
-GNAT does not require a separate pragma @code{Export}, but if none is
-present, @code{Convention Ada} is assumed, which is usually
-not what is wanted, so it is usually appropriate to use this
-pragma in conjunction with a @code{Export} or @code{Convention}
-pragma that specifies the desired foreign convention.
-Pragma @code{Export_Function}
-(and @code{Export}, if present) must appear in the same declarative
-region as the function to which they apply.
-
-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 @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
-
-Special treatment is given if the EXTERNAL is an explicit null
-string or a static string expressions that evaluates to the null
-string. In this case, no external name is generated. This form
-still allows the specification of parameter mechanisms.
-
-@node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{60}
-@section Pragma Export_Object
-
-
-Syntax:
-
-@example
-pragma Export_Object (
-      [Internal =>] LOCAL_NAME
-   [, [External =>] EXTERNAL_SYMBOL]
-   [, [Size     =>] EXTERNAL_SYMBOL]);
-
-EXTERNAL_SYMBOL ::=
-  IDENTIFIER
-| static_string_EXPRESSION
-@end example
-
-This pragma designates an object as exported, and apart from the
-extended rules for external symbols, is identical in effect to the use of
-the normal @code{Export} pragma applied to an object.  You may use a
-separate Export pragma (and you probably should from the point of view
-of portability), but it is not required.  @code{Size} is syntax checked,
-but otherwise ignored by GNAT.
-
-@node Pragma Export_Procedure,Pragma Export_Valued_Procedure,Pragma Export_Object,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{61}
-@section Pragma Export_Procedure
-
-
-Syntax:
-
-@example
-pragma Export_Procedure (
-     [Internal        =>] LOCAL_NAME
-  [, [External        =>] EXTERNAL_SYMBOL]
-  [, [Parameter_Types =>] PARAMETER_TYPES]
-  [, [Mechanism       =>] MECHANISM]);
-
-EXTERNAL_SYMBOL ::=
-  IDENTIFIER
-| static_string_EXPRESSION
-| ""
-
-PARAMETER_TYPES ::=
-  null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
-  subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
-  MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
-  [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::= Value | Reference
-@end example
-
-This pragma is identical to @code{Export_Function} except that it
-applies to a procedure rather than a function and the parameters
-@code{Result_Type} and @code{Result_Mechanism} are not permitted.
-GNAT does not require a separate pragma @code{Export}, but if none is
-present, @code{Convention Ada} is assumed, which is usually
-not what is wanted, so it is usually appropriate to use this
-pragma in conjunction with a @code{Export} or @code{Convention}
-pragma that specifies the desired foreign convention.
-
-@geindex Suppressing external name
-
-Special treatment is given if the EXTERNAL is an explicit null
-string or a static string expressions that evaluates to the null
-string. In this case, no external name is generated. This form
-still allows the specification of parameter mechanisms.
-
-@node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Procedure,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{62}
-@section Pragma Export_Valued_Procedure
-
-
-Syntax:
-
-@example
-pragma Export_Valued_Procedure (
-     [Internal        =>] LOCAL_NAME
-  [, [External        =>] EXTERNAL_SYMBOL]
-  [, [Parameter_Types =>] PARAMETER_TYPES]
-  [, [Mechanism       =>] MECHANISM]);
-
-EXTERNAL_SYMBOL ::=
-  IDENTIFIER
-| static_string_EXPRESSION
-| ""
-
-PARAMETER_TYPES ::=
-  null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
-  subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
-  MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
-  [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::= Value | Reference
-@end example
-
-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 @code{out} and @code{in out}
-parameters in interfacing to external functions (which are not permitted
-in Ada functions).
-GNAT does not require a separate pragma @code{Export}, but if none is
-present, @code{Convention Ada} is assumed, which is almost certainly
-not what is wanted since the whole point of this pragma is to interface
-with foreign language functions, so it is usually appropriate to use this
-pragma in conjunction with a @code{Export} or @code{Convention}
-pragma that specifies the desired foreign convention.
-
-@geindex Suppressing external name
-
-Special treatment is given if the EXTERNAL is an explicit null
-string or a static string expressions that evaluates to the null
-string. In this case, no external name is generated. This form
-still allows the specification of parameter mechanisms.
-
-@node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{63}
-@section Pragma Extend_System
-
-
-@geindex System
-@geindex extending
-
-@geindex DEC Ada 83
-
-Syntax:
-
-@example
-pragma Extend_System ([Name =>] IDENTIFIER);
-@end example
-
-This pragma is used to provide backwards compatibility with other
-implementations that extend the facilities of package @code{System}.  In
-GNAT, @code{System} contains only the definitions that are present in
-the Ada RM.  However, other implementations, notably the DEC Ada 83
-implementation, provide many extensions to package @code{System}.
-
-For each such implementation accommodated by this pragma, GNAT provides a
-package @code{Aux_@var{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83
-implementation, which provides the required additional definitions.  You
-can use this package in two ways.  You can @code{with} it in the normal
-way and access entities either by selection or using a @code{use}
-clause.  In this case no special processing is required.
-
-However, if existing code contains references such as
-@code{System.@var{xxx}} where `xxx' is an entity in the extended
-definitions provided in package @code{System}, you may use this pragma
-to extend visibility in @code{System} in a non-standard way that
-provides greater compatibility with the existing code.  Pragma
-@code{Extend_System} is a configuration pragma whose single argument is
-the name of the package containing the extended definition
-(e.g., @code{Aux_DEC} for the DEC Ada case).  A unit compiled under
-control of this pragma will be processed using special visibility
-processing that looks in package @code{System.Aux_@var{xxx}} where
-@code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
-package @code{System}, but not found in package @code{System}.
-
-You can use this pragma either to access a predefined @code{System}
-extension supplied with the compiler, for example @code{Aux_DEC} or
-you can construct your own extension unit following the above
-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 `-gnatg' switch
-for compiling System units, as explained in the
-GNAT User’s Guide.
-
-@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{64}
-@section Pragma Extensions_Allowed
-
-
-@geindex Ada Extensions
-
-@geindex GNAT Extensions
-
-Syntax:
-
-@example
-pragma Extensions_Allowed (On | Off | All);
-@end example
-
-This configuration pragma enables (via the “On” or “All” argument) or disables
-(via the “Off” argument) the implementation extension mode; the pragma takes
-precedence over the `-gnatX' and `-gnatX0' command switches.
-
-If an argument of “All” is specified, the latest version of the Ada language
-is implemented (currently Ada 2022) and, in addition, a number
-of GNAT specific extensions are recognized. These extensions are listed
-below. An argument of “On” has the same effect except that only
-some, not all, of the listed extensions are enabled; those extensions
-are identified below.
-
-
-@itemize *
-
-@item 
-Constrained attribute for generic objects
-
-The @code{Constrained} attribute is permitted for objects of
-generic types. The result indicates if the corresponding actual
-is constrained.
-
-@item 
-@code{Static} aspect on intrinsic functions
-
-The Ada 202x @code{Static} aspect can be specified on Intrinsic imported
-functions and the compiler will evaluate some of these intrinsic statically,
-in particular the @code{Shift_Left} and @code{Shift_Right} intrinsics.
-
-An Extensions_Allowed pragma argument of “On” enables this extension.
-
-@item 
-@code{[]} aggregates
-
-This new aggregate syntax for arrays and containers is provided under -gnatX
-to experiment and confirm this new language syntax.
-
-@item 
-Additional @code{when} constructs
-
-In addition to the @code{exit when CONDITION} control structure, several
-additional constructs are allowed following this format. Including
-@code{return when CONDITION}, @code{goto when CONDITION}, and
-@code{raise [with EXCEPTION_MESSAGE] when CONDITION.}
-
-Some examples:
-
-@example
-return Result when Variable > 10;
-
-raise Program_Error with "Element is null" when Element = null;
-
-goto End_Of_Subprogram when Variable = -1;
-@end example
-
-@item 
-Casing on composite values (aka pattern matching)
-
-The selector for a case statement may be of a composite type, subject to
-some restrictions (described below). Aggregate syntax is used for choices
-of such a case statement; however, in cases where a “normal” aggregate would
-require a discrete value, a discrete subtype may be used instead; box
-notation can also be used to match all values.
-
-Consider this example:
-
-@example
-type Rec is record
-   F1, F2 : Integer;
-end record;
-
-procedure Caser_1 (X : Rec) is
-begin
-   case X is
-      when (F1 => Positive, F2 => Positive) =>
-         Do_This;
-      when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) =>
-         Do_That;
-      when others =>
-          Do_The_Other_Thing;
-   end case;
-end Caser_1;
-@end example
-
-If Caser_1 is called and both components of X are positive, then
-Do_This will be called; otherwise, if either component is nonnegative
-then Do_That will be called; otherwise, Do_The_Other_Thing will be called.
-
-If the set of values that match the choice(s) of an earlier alternative
-overlaps the corresponding set of a later alternative, then the first
-set shall be a proper subset of the second (and the later alternative
-will not be executed if the earlier alternative “matches”). All possible
-values of the composite type shall be covered. The composite type of the
-selector shall be an array or record type that is neither limited
-class-wide. Currently, a “when others =>” case choice is required; it is
-intended that this requirement will be relaxed at some point.
-
-If a subcomponent’s subtype does not meet certain restrictions, then
-the only value that can be specified for that subcomponent in a case
-choice expression is a “box” component association (which matches all
-possible values for the subcomponent). This restriction applies if
-
-
-@itemize -
-
-@item 
-the component subtype is not a record, array, or discrete type; or
-
-@item 
-the component subtype is subject to a non-static constraint or
-has a predicate; or
-
-@item 
-the component type is an enumeration type that is subject to an
-enumeration representation clause; or
-
-@item 
-the component type is a multidimensional array type or an
-array type with a nonstatic index subtype.
-@end itemize
-
-Support for casing on arrays (and on records that contain arrays) is
-currently subject to some restrictions. Non-positional
-array aggregates are not supported as (or within) case choices. Likewise
-for array type and subtype names. The current implementation exceeds
-compile-time capacity limits in some annoyingly common scenarios; the
-message generated in such cases is usually “Capacity exceeded in compiling
-case statement with composite selector type”.
-
-In addition, pattern bindings are supported. This is a mechanism
-for binding a name to a component of a matching value for use within
-an alternative of a case statement. For a component association
-that occurs within a case choice, the expression may be followed by
-“is <identifier>”. In the special case of a “box” component association,
-the identifier may instead be provided within the box. Either of these
-indicates that the given identifer denotes (a constant view of) the matching
-subcomponent of the case selector. Binding is not yet supported for arrays
-or subcomponents thereof.
-
-Consider this example (which uses type Rec from the previous example):
-
-@example
-procedure Caser_2 (X : Rec) is
-begin
-   case X is
-      when (F1 => Positive is Abc, F2 => Positive) =>
-         Do_This (Abc)
-      when (F1 => Natural is N1, F2 => <N2>) |
-           (F1 => <N2>, F2 => Natural is N1) =>
-         Do_That (Param_1 => N1, Param_2 => N2);
-      when others =>
-         Do_The_Other_Thing;
-   end case;
-end Caser_2;
-@end example
-
-This example is the same as the previous one with respect to
-determining whether Do_This, Do_That, or Do_The_Other_Thing will
-be called. But for this version, Do_This takes a parameter and Do_That
-takes two parameters. If Do_This is called, the actual parameter in the
-call will be X.F1.
-
-If Do_That is called, the situation is more complex because there are two
-choices for that alternative. If Do_That is called because the first choice
-matched (i.e., because X.F1 is nonnegative and either X.F1 or X.F2 is zero
-or negative), then the actual parameters of the call will be (in order)
-X.F1 and X.F2. If Do_That is called because the second choice matched (and
-the first one did not), then the actual parameters will be reversed.
-
-Within the choice list for single alternative, each choice must
-define the same set of bindings and the component subtypes for
-for a given identifer must all statically match. Currently, the case
-of a binding for a nondiscrete component is not implemented.
-
-An Extensions_Allowed pragma argument of “On” enables this extension.
-
-@item 
-Fixed lower bounds for array types and subtypes
-
-Unconstrained array types and subtypes can be specified with a lower bound
-that is fixed to a certain value, by writing an index range that uses the
-syntax “<lower-bound-expression> .. <>”. This guarantees that all objects
-of the type or subtype will have the specified lower bound.
-
-For example, a matrix type with fixed lower bounds of zero for each
-dimension can be declared by the following:
-
-@example
-type Matrix is
-  array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer;
-@end example
-
-Objects of type Matrix declared with an index constraint must have index
-ranges starting at zero:
-
-@example
-M1 : Matrix (0 .. 9, 0 .. 19);
-M2 : Matrix (2 .. 11, 3 .. 22);  -- Warning about bounds; will raise CE
-@end example
-
-Similarly, a subtype of String can be declared that specifies the lower
-bound of objects of that subtype to be 1:
-
-@quotation
-
-@example
-subtype String_1 is String (1 .. <>);
-@end example
-@end quotation
-
-If a string slice is passed to a formal of subtype String_1 in a call to
-a subprogram S, the slice’s bounds will “slide” so that the lower bound
-is 1. Within S, the lower bound of the formal is known to be 1, so, unlike
-a normal unconstrained String formal, there is no need to worry about
-accounting for other possible lower-bound values. Sliding of bounds also
-occurs in other contexts, such as for object declarations with an
-unconstrained subtype with fixed lower bound, as well as in subtype
-conversions.
-
-Use of this feature increases safety by simplifying code, and can also
-improve the efficiency of indexing operations, since the compiler statically
-knows the lower bound of unconstrained array formals when the formal’s
-subtype has index ranges with static fixed lower bounds.
-
-An Extensions_Allowed pragma argument of “On” enables this extension.
-
-@item 
-Prefixed-view notation for calls to primitive subprograms of untagged types
-
-Since Ada 2005, calls to primitive subprograms of a tagged type that
-have a “prefixed view” (see RM 4.1.3(9.2)) have been allowed to be
-written using the form of a selected_component, with the first actual
-parameter given as the prefix and the name of the subprogram as a
-selector. This prefixed-view notation for calls is extended so as to
-also allow such syntax for calls to primitive subprograms of untagged
-types. The primitives of an untagged type T that have a prefixed view
-are those where the first formal parameter of the subprogram either
-is of type T or is an anonymous access parameter whose designated type
-is T. For a type that has a component that happens to have the same
-simple name as one of the type’s primitive subprograms, where the
-component is visible at the point of a selected_component using that
-name, preference is given to the component in a selected_component
-(as is currently the case for tagged types with such component names).
-
-An Extensions_Allowed pragma argument of “On” enables this extension.
-
-@item 
-Expression defaults for generic formal functions
-
-The declaration of a generic formal function is allowed to specify
-an expression as a default, using the syntax of an expression function.
-
-Here is an example of this feature:
-
-@example
-generic
-   type T is private;
-   with function Copy (Item : T) return T is (Item); -- Defaults to Item
-package Stacks is
-
-   type Stack is limited private;
-
-   procedure Push (S : in out Stack; X : T); -- Calls Copy on X
-
-   function Pop (S : in out Stack) return T; -- Calls Copy to return item
-
-private
-   -- ...
-end Stacks;
-@end example
-@end itemize
-
-@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{65}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{66}
-@section Pragma Extensions_Visible
-
-
-Syntax:
-
-@example
-pragma Extensions_Visible [ (static_boolean_EXPRESSION) ];
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{67}
-@section Pragma External
-
-
-Syntax:
-
-@example
-pragma External (
-  [   Convention    =>] convention_IDENTIFIER,
-  [   Entity        =>] LOCAL_NAME
-  [, [External_Name =>] static_string_EXPRESSION ]
-  [, [Link_Name     =>] static_string_EXPRESSION ]);
-@end example
-
-This pragma is identical in syntax and semantics to pragma
-@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
-@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{68}
-@section Pragma External_Name_Casing
-
-
-@geindex Dec Ada 83 casing compatibility
-
-@geindex External Names
-@geindex casing
-
-@geindex Casing of External names
-
-Syntax:
-
-@example
-pragma External_Name_Casing (
-  Uppercase | Lowercase
-  [, Uppercase | Lowercase | As_Is]);
-@end example
-
-This pragma provides control over the casing of external names associated
-with Import and Export pragmas.  There are two cases to consider:
-
-
-@itemize *
-
-@item 
-Implicit external names
-
-Implicit external names are derived from identifiers.  The most common case
-arises when a standard Ada Import or Export pragma is used with only two
-arguments, as in:
-
-@example
-pragma Import (C, C_Routine);
-@end example
-
-Since Ada is a case-insensitive language, the spelling of the identifier in
-the Ada source program does not provide any information on the desired
-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 @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
-compatible Import and Export pragmas where an external name is explicitly
-specified using an identifier rather than a string.
-
-@item 
-Explicit external names
-
-Explicit external names are given as string literals.  The most common case
-arises when a standard Ada Import or Export pragma is used with three
-arguments, as in:
-
-@example
-pragma Import (C, C_Routine, "C_routine");
-@end example
-
-In this case, the string literal normally provides the exact casing required
-for the external name.  The second argument of pragma
-@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
-@code{As_Is} provides the normal default behavior in which the casing is
-taken from the string provided.
-@end itemize
-
-This pragma may appear anywhere that a pragma is valid. In particular, it
-can be used as a configuration pragma in the @code{gnat.adc} file, in which
-case it applies to all subsequent compilations, or it can be used as a program
-unit pragma, in which case it only applies to the current unit, or it can
-be used more locally to control individual Import/Export pragmas.
-
-It was primarily intended for use with OpenVMS systems, where many
-compilers convert all symbols to upper case by default.  For interfacing to
-such compilers (e.g., the DEC C compiler), it may be convenient to use
-the pragma:
-
-@example
-pragma External_Name_Casing (Uppercase, Uppercase);
-@end example
-
-to enforce the upper casing of all external symbols.
-
-@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{69}
-@section Pragma Fast_Math
-
-
-Syntax:
-
-@example
-pragma Fast_Math;
-@end example
-
-This is a configuration pragma which activates a mode in which speed is
-considered more important for floating-point operations than absolutely
-accurate adherence to the requirements of the standard. Currently the
-following operations are affected:
-
-
-@table @asis
-
-@item `Complex Multiplication'
-
-The normal simple formula for complex multiplication can result in intermediate
-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 @code{Ada.Numerics.Generic_Complex_Types}
-under control of the pragma, rather than use the preinstantiated versions.
-@end table
-
-@node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6a}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6b}
-@section Pragma Favor_Top_Level
-
-
-Syntax:
-
-@example
-pragma Favor_Top_Level (type_NAME);
-@end example
-
-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
-@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 @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{6c}
-@section Pragma Finalize_Storage_Only
-
-
-Syntax:
-
-@example
-pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
-@end example
-
-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 @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{6d}
-@section Pragma Float_Representation
-
-
-Syntax:
-
-@example
-pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
-
-FLOAT_REP ::= VAX_Float | IEEE_Float
-@end example
-
-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 @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 @code{IEEE_Float} to specify the use of IEEE format, as follows:
-
-
-@itemize *
-
-@item 
-For a digits value of 6, 32-bit IEEE short format will be used.
-
-@item 
-For a digits value of 15, 64-bit IEEE long format will be used.
-
-@item 
-No other value of digits is permitted.
-@end itemize
-
-@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6e}@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{6f}
-@section Pragma Ghost
-
-
-Syntax:
-
-@example
-pragma Ghost [ (static_boolean_EXPRESSION) ];
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{70}@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{71}
-@section Pragma Global
-
-
-Syntax:
-
-@example
-pragma Global (GLOBAL_SPECIFICATION);
-
-GLOBAL_SPECIFICATION ::=
-     null
-  | (GLOBAL_LIST)
-  | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@})
-
-MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST
-
-MODE_SELECTOR ::= In_Out | Input | Output | Proof_In
-GLOBAL_LIST   ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@})
-GLOBAL_ITEM   ::= NAME
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{72}
-@section Pragma Ident
-
-
-Syntax:
-
-@example
-pragma Ident (static_string_EXPRESSION);
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{73}
-@section Pragma Ignore_Pragma
-
-
-Syntax:
-
-@example
-pragma Ignore_Pragma (pragma_IDENTIFIER);
-@end example
-
-This is a configuration pragma
-that takes a single argument that is a simple identifier. Any subsequent
-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
-mode, or during porting of legacy code.
-
-@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{74}
-@section Pragma Implementation_Defined
-
-
-Syntax:
-
-@example
-pragma Implementation_Defined (local_NAME);
-@end example
-
-This pragma marks a previously declared entity as implementation-defined.
-For an overloaded entity, applies to the most recent homonym.
-
-@example
-pragma Implementation_Defined;
-@end example
-
-The form with no arguments appears anywhere within a scope, most
-typically a package spec, and indicates that all entities that are
-defined within the package spec are Implementation_Defined.
-
-This pragma is used within the GNAT runtime library to identify
-implementation-defined entities introduced in language-defined units,
-for the purpose of implementing the No_Implementation_Identifiers
-restriction.
-
-@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{75}
-@section Pragma Implemented
-
-
-Syntax:
-
-@example
-pragma Implemented (procedure_LOCAL_NAME, implementation_kind);
-
-implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any
-@end example
-
-This is an Ada 2012 representation pragma which applies to protected, task
-and synchronized interface primitives. The use of pragma Implemented provides
-a way to impose a static requirement on the overriding operation by adhering
-to one of the three implementation kinds: entry, protected procedure or any of
-the above. This pragma is available in all earlier versions of Ada as an
-implementation-defined pragma.
-
-@example
-type Synch_Iface is synchronized interface;
-procedure Prim_Op (Obj : in out Iface) is abstract;
-pragma Implemented (Prim_Op, By_Protected_Procedure);
-
-protected type Prot_1 is new Synch_Iface with
-   procedure Prim_Op;  --  Legal
-end Prot_1;
-
-protected type Prot_2 is new Synch_Iface with
-   entry Prim_Op;      --  Illegal
-end Prot_2;
-
-task type Task_Typ is new Synch_Iface with
-   entry Prim_Op;      --  Illegal
-end Task_Typ;
-@end example
-
-When applied to the procedure_or_entry_NAME of a requeue statement, pragma
-Implemented determines the runtime behavior of the requeue. Implementation kind
-By_Entry guarantees that the action of requeueing will proceed from an entry to
-another entry. Implementation kind By_Protected_Procedure transforms the
-requeue into a dispatching call, thus eliminating the chance of blocking. Kind
-By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on
-the target’s overriding subprogram kind.
-
-@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{76}
-@section Pragma Implicit_Packing
-
-
-@geindex Rational Profile
-
-Syntax:
-
-@example
-pragma Implicit_Packing;
-@end example
-
-This is a configuration pragma that requests implicit packing for packed
-arrays for which a size clause is given but no explicit pragma Pack or
-specification of Component_Size is present. It also applies to records
-where no record representation clause is present. Consider this example:
-
-@example
-type R is array (0 .. 7) of Boolean;
-for R'Size use 8;
-@end example
-
-In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause
-does not change the layout of a composite object. So the Size clause in the
-above example is normally rejected, since the default layout of the array uses
-8-bit components, and thus the array requires a minimum of 64 bits.
-
-If this declaration is compiled in a region of code covered by an occurrence
-of the configuration pragma Implicit_Packing, then the Size clause in this
-and similar examples will cause implicit packing and thus be accepted. For
-this implicit packing to occur, the type in question must be an array of small
-components whose size is known at compile time, and the Size clause must
-specify the exact size that corresponds to the number of elements in the array
-multiplied by the size in bits of the component type (both single and
-multi-dimensioned arrays can be controlled with this pragma).
-
-@geindex Array packing
-
-Similarly, the following example shows the use in the record case
-
-@example
-type r is record
-   a, b, c, d, e, f, g, h : boolean;
-   chr                    : character;
-end record;
-for r'size use 16;
-@end example
-
-Without a pragma Pack, each Boolean field requires 8 bits, so the
-minimum size is 72 bits, but with a pragma Pack, 16 bits would be
-sufficient. The use of pragma Implicit_Packing allows this record
-declaration to compile without an explicit pragma Pack.
-
-@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{77}
-@section Pragma Import_Function
-
-
-Syntax:
-
-@example
-pragma Import_Function (
-     [Internal         =>] LOCAL_NAME,
-  [, [External         =>] EXTERNAL_SYMBOL]
-  [, [Parameter_Types  =>] PARAMETER_TYPES]
-  [, [Result_Type      =>] SUBTYPE_MARK]
-  [, [Mechanism        =>] MECHANISM]
-  [, [Result_Mechanism =>] MECHANISM_NAME]);
-
-EXTERNAL_SYMBOL ::=
-  IDENTIFIER
-| static_string_EXPRESSION
-
-PARAMETER_TYPES ::=
-  null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
-  subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
-  MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
-  [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::=
-  Value
-| Reference
-@end example
-
-This pragma is used in conjunction with a pragma @code{Import} to
-specify additional information for an imported function.  The pragma
-@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 @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 @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 @code{'Access} attribute can be used to match an
-anonymous access parameter.
-
-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
-parameter by parameter basis using either positional or named
-notation.  If the mechanism is not specified, the default mechanism
-is used.
-
-@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{78}
-@section Pragma Import_Object
-
-
-Syntax:
-
-@example
-pragma Import_Object (
-     [Internal =>] LOCAL_NAME
-  [, [External =>] EXTERNAL_SYMBOL]
-  [, [Size     =>] EXTERNAL_SYMBOL]);
-
-EXTERNAL_SYMBOL ::=
-  IDENTIFIER
-| static_string_EXPRESSION
-@end example
-
-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 @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).  @code{size} is syntax checked, but otherwise ignored by
-GNAT.
-
-@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{79}
-@section Pragma Import_Procedure
-
-
-Syntax:
-
-@example
-pragma Import_Procedure (
-     [Internal        =>] LOCAL_NAME
-  [, [External        =>] EXTERNAL_SYMBOL]
-  [, [Parameter_Types =>] PARAMETER_TYPES]
-  [, [Mechanism       =>] MECHANISM]);
-
-EXTERNAL_SYMBOL ::=
-  IDENTIFIER
-| static_string_EXPRESSION
-
-PARAMETER_TYPES ::=
-  null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
-  subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
-  MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
-  [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::= Value | Reference
-@end example
-
-This pragma is identical to @code{Import_Function} except that it
-applies to a procedure rather than a function and the parameters
-@code{Result_Type} and @code{Result_Mechanism} are not permitted.
-
-@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7a}
-@section Pragma Import_Valued_Procedure
-
-
-Syntax:
-
-@example
-pragma Import_Valued_Procedure (
-     [Internal        =>] LOCAL_NAME
-  [, [External        =>] EXTERNAL_SYMBOL]
-  [, [Parameter_Types =>] PARAMETER_TYPES]
-  [, [Mechanism       =>] MECHANISM]);
-
-EXTERNAL_SYMBOL ::=
-  IDENTIFIER
-| static_string_EXPRESSION
-
-PARAMETER_TYPES ::=
-  null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
-  subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
-  MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
-  [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::= Value | Reference
-@end example
-
-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 @code{out} and @code{in out}
-parameters in interfacing to external functions (which are not permitted
-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
-basis using either positional or named notation.  If the mechanism is not
-specified, the default mechanism is used.
-
-Note that it is important to use this pragma in conjunction with a separate
-pragma Import that specifies the desired convention, since otherwise the
-default convention is Ada, which is almost certainly not what is required.
-
-@node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7b}
-@section Pragma Independent
-
-
-Syntax:
-
-@example
-pragma Independent (Local_NAME);
-@end example
-
-This pragma is standard in Ada 2012 mode (which also provides an aspect
-of the same name). It is also available as an implementation-defined
-pragma in all earlier versions. It specifies that the
-designated object or all objects of the designated type must be
-independently addressable. This means that separate tasks can safely
-manipulate such objects. For example, if two components of a record are
-independent, then two separate tasks may access these two components.
-This may place
-constraints on the representation of the object (for instance prohibiting
-tight packing).
-
-@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7c}
-@section Pragma Independent_Components
-
-
-Syntax:
-
-@example
-pragma Independent_Components (Local_NAME);
-@end example
-
-This pragma is standard in Ada 2012 mode (which also provides an aspect
-of the same name). It is also available as an implementation-defined
-pragma in all earlier versions. It specifies that the components of the
-designated object, or the components of each object of the designated
-type, must be
-independently addressable. This means that separate tasks can safely
-manipulate separate components in the composite object. This may place
-constraints on the representation of the object (for instance prohibiting
-tight packing).
-
-@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{7d}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{7e}
-@section Pragma Initial_Condition
-
-
-Syntax:
-
-@example
-pragma Initial_Condition (boolean_EXPRESSION);
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{7f}
-@section Pragma Initialize_Scalars
-
-
-@geindex debugging with Initialize_Scalars
-
-Syntax:
-
-@example
-pragma Initialize_Scalars
-  [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ];
-
-TYPE_VALUE_PAIR ::=
-  SCALAR_TYPE => static_EXPRESSION
-
-SCALAR_TYPE :=
-  Short_Float
-| Float
-| Long_Float
-| Long_Long_Flat
-| Signed_8
-| Signed_16
-| Signed_32
-| Signed_64
-| Unsigned_8
-| Unsigned_16
-| Unsigned_32
-| Unsigned_64
-@end example
-
-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, without needing to recompile the run-time
-library. In the case where some units are compiled with the pragma, and some
-without, then a declaration of a variable where the type is defined in package
-Standard or is locally declared will always be subject to initialization, as
-will any declaration of a scalar variable. For composite variables, whether the
-variable is initialized may also depend on whether the package in which the
-type of the variable is declared is compiled with the pragma.
-
-The other important difference is that the programmer can control the value
-used for initializing scalar objects. This effect can be achieved in several
-different ways:
-
-
-@itemize *
-
-@item 
-At compile time, the programmer can specify the invalid value for a
-particular family of scalar types using the optional arguments of the pragma.
-
-The compile-time approach is intended to optimize the generated code for the
-pragma, by possibly using fast operations such as @code{memset}. Note that such
-optimizations require using values where the bytes all have the same binary
-representation.
-
-@item 
-At bind time, the programmer has several options:
-
-
-@itemize *
-
-@item 
-Initialization with invalid values (similar to Normalize_Scalars, though
-for Initialize_Scalars it is not always possible to determine the invalid
-values in complex cases like signed component fields with nonstandard
-sizes).
-
-@item 
-Initialization with high values.
-
-@item 
-Initialization with low values.
-
-@item 
-Initialization with a specific bit pattern.
-@end itemize
-
-See the GNAT User’s Guide for binder options for specifying these cases.
-
-The bind-time approach is intended to provide fast turnaround for testing
-with different values, without having to recompile the program.
-
-@item 
-At execution time, the programmer can specify the invalid values using an
-environment variable. See the GNAT User’s Guide for details.
-
-The execution-time approach is intended to provide fast turnaround for
-testing with different values, without having to recompile and rebind the
-program.
-@end itemize
-
-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 `-gnatV' flag in the GNAT User’s Guide) in conjunction with pragma
-@code{Initialize_Scalars} provides a powerful new tool to assist in the detection
-of problems caused by uninitialized variables.
-
-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 checking (see description of stack checking in the
-GNAT User’s Guide) when using this pragma.
-
-@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{80}@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{81}
-@section Pragma Initializes
-
-
-Syntax:
-
-@example
-pragma Initializes (INITIALIZATION_LIST);
-
-INITIALIZATION_LIST ::=
-     null
-  | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@})
-
-INITIALIZATION_ITEM ::= name [=> INPUT_LIST]
-
-INPUT_LIST ::=
-     null
-  |  INPUT
-  | (INPUT @{, INPUT@})
-
-INPUT ::= name
-@end example
-
-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
-@anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{82}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{83}
-@section Pragma Inline_Always
-
-
-Syntax:
-
-@example
-pragma Inline_Always (NAME [, NAME]);
-@end example
-
-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 `-gnatn' or `-gnatN' or the optimization level.
-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 @code{NAME}.
-
-@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{84}
-@section Pragma Inline_Generic
-
-
-Syntax:
-
-@example
-pragma Inline_Generic (GNAME @{, GNAME@});
-
-GNAME ::= generic_unit_NAME | generic_instance_NAME
-@end example
-
-This pragma is provided for compatibility with Dec Ada 83. It has
-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.
-
-@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{85}
-@section Pragma Interface
-
-
-Syntax:
-
-@example
-pragma Interface (
-     [Convention    =>] convention_identifier,
-     [Entity        =>] local_NAME
-  [, [External_Name =>] static_string_expression]
-  [, [Link_Name     =>] static_string_expression]);
-@end example
-
-This pragma is identical in syntax and semantics to
-the standard Ada pragma @code{Import}.  It is provided for compatibility
-with Ada 83.  The definition is upwards compatible both with pragma
-@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 @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 @code{Import} pragmas). This is useful in
-maintaining Ada 83/Ada 95 compatibility and is compatible with other
-Ada 83 compilers.
-
-@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{86}
-@section Pragma Interface_Name
-
-
-Syntax:
-
-@example
-pragma Interface_Name (
-     [Entity        =>] LOCAL_NAME
-  [, [External_Name =>] static_string_EXPRESSION]
-  [, [Link_Name     =>] static_string_EXPRESSION]);
-@end example
-
-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 @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{87}
-@section Pragma Interrupt_Handler
-
-
-Syntax:
-
-@example
-pragma Interrupt_Handler (procedure_LOCAL_NAME);
-@end example
-
-This program unit pragma is supported for parameterless protected procedures
-as described in Annex C of the Ada Reference Manual.
-
-@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{88}
-@section Pragma Interrupt_State
-
-
-Syntax:
-
-@example
-pragma Interrupt_State
- ([Name  =>] value,
-  [State =>] SYSTEM | RUNTIME | USER);
-@end example
-
-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 @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 @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
-@code{abort} statement and stack overflow checking.
-
-Pragma @code{Interrupt_State} provides a general mechanism for overriding
-such uses of interrupts.  It subsumes the functionality of pragma
-@code{Unreserve_All_Interrupts}.  Pragma @code{Interrupt_State} is not
-available on Windows.  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
-as reserved.
-
-Interrupts can be in one of three states:
-
-
-@itemize *
-
-@item 
-System
-
-The interrupt is reserved (no Ada handler can be installed), and the
-Ada run-time may not install a handler. As a result you are guaranteed
-standard system default action if this interrupt is raised. This also allows
-installing a low level handler via C APIs such as sigaction(), outside
-of Ada control.
-
-@item 
-Runtime
-
-The interrupt is reserved (no Ada handler can be installed). The run time
-is allowed to install a handler for internal control purposes, but is
-not required to do so.
-
-@item 
-User
-
-The interrupt is unreserved.  The user may install an Ada handler via
-Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide
-some other action.
-@end itemize
-
-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
-given interrupt is specified. It may appear anywhere a pragma is legal.
-
-The effect is to move the interrupt to the specified state.
-
-By declaring interrupts to be SYSTEM, you guarantee the standard system
-action, such as a core dump.
-
-By declaring interrupts to be USER, you guarantee that you can install
-a handler.
-
-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 @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 @code{abort} statement.
-
-@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{89}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8a}
-@section Pragma Invariant
-
-
-Syntax:
-
-@example
-pragma Invariant
-  ([Entity =>]    private_type_LOCAL_NAME,
-   [Check  =>]    EXPRESSION
-   [,[Message =>] String_Expression]);
-@end example
-
-This pragma provides exactly the same capabilities as the Type_Invariant aspect
-defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The
-Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it
-requires the use of the aspect syntax, which is not available except in 2012
-mode, it is not possible to use the Type_Invariant aspect in earlier versions
-of Ada. However the Invariant pragma may be used in any version of Ada. Also
-note that the aspect Invariant is a synonym in GNAT for the aspect
-Type_Invariant, but there is no pragma Type_Invariant.
-
-The pragma must appear within the visible part of the package specification,
-after the type to which its Entity argument appears. As with the Invariant
-aspect, the Check expression is not analyzed until the end of the visible
-part of the package, so it may contain forward references. The Message
-argument, if present, provides the exception message used if the invariant
-is violated. If no Message parameter is provided, a default message that
-identifies the line on which the pragma appears is used.
-
-It is permissible to have multiple Invariants for the same type entity, in
-which case they are and’ed together. It is permissible to use this pragma
-in Ada 2012 mode, but you cannot have both an invariant aspect and an
-invariant pragma for the same entity.
-
-For further details on the use of this pragma, see the Ada 2012 documentation
-of the Type_Invariant aspect.
-
-@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8b}
-@section Pragma Keep_Names
-
-
-Syntax:
-
-@example
-pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
-@end example
-
-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 @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 @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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8c}
-@section Pragma License
-
-
-@geindex License checking
-
-Syntax:
-
-@example
-pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
-@end example
-
-This pragma is provided to allow automated checking for appropriate license
-conditions with respect to the standard and modified GPL.  A pragma
-@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:
-
-
-@itemize *
-
-@item 
-Unrestricted
-This is used for a unit that can be freely used with no license restrictions.
-Examples of such units are public domain units, and units from the Ada
-Reference Manual.
-
-@item 
-GPL
-This is used for a unit that is licensed under the unmodified GPL, and which
-therefore cannot be @code{with}ed by a restricted unit.
-
-@item 
-Modified_GPL
-This is used for a unit licensed under the GNAT modified GPL that includes
-a special exception paragraph that specifically permits the inclusion of
-the unit in programs without requiring the entire program to be released
-under the GPL.
-
-@item 
-Restricted
-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 @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 @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.
-
-A GNAT license header starts with a line containing 78 hyphens.  The following
-comment text is searched for the appearance of any of the following strings.
-
-If the string ‘GNU General Public License’ is found, then the unit is assumed
-to have GPL license, unless the string ‘As a special exception’ follows, in
-which case the license is assumed to be modified GPL.
-
-If one of the strings
-‘This specification is adapted from the Ada Semantic Interface’ or
-‘This specification is derived from the Ada Reference Manual’ is found
-then the unit is assumed to be unrestricted.
-
-These default actions means that a program with a restricted license pragma
-will automatically get warnings if a GPL unit is inappropriately
-@code{with}ed.  For example, the program:
-
-@example
-with Sem_Ch3;
-with GNAT.Sockets;
-procedure Secret_Stuff is
-  ...
-end Secret_Stuff
-@end example
-
-if compiled with pragma @code{License} (@code{Restricted}) in a
-@code{gnat.adc} file will generate the warning:
-
-@example
-1.  with Sem_Ch3;
-        |
-   >>> license of withed unit "Sem_Ch3" is incompatible
-
-2.  with GNAT.Sockets;
-3.  procedure Secret_Stuff is
-@end example
-
-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 @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
-@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{8d}
-@section Pragma Link_With
-
-
-Syntax:
-
-@example
-pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
-@end example
-
-This pragma is provided for compatibility with certain Ada 83 compilers.
-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:
-
-@example
-pragma Link_With ("-labc -ldef");
-@end example
-
-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.
-
-@node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{8e}
-@section Pragma Linker_Alias
-
-
-Syntax:
-
-@example
-pragma Linker_Alias (
-  [Entity =>] LOCAL_NAME,
-  [Target =>] static_string_EXPRESSION);
-@end example
-
-@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 @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 @code{pragma Import}
-or @code{pragma Export}.
-
-Not all target machines support this pragma. On some of them it is accepted
-only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}.
-
-@example
---  Example of the use of pragma Linker_Alias
-
-package p is
-  i : Integer := 1;
-  pragma Export (C, i);
-
-  new_name_for_i : Integer;
-  pragma Linker_Alias (new_name_for_i, "i");
-end p;
-@end example
-
-@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{8f}
-@section Pragma Linker_Constructor
-
-
-Syntax:
-
-@example
-pragma Linker_Constructor (procedure_LOCAL_NAME);
-@end example
-
-@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 @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.
-
-Because of these specific contexts, the set of operations such a procedure
-can perform is very limited and the type of objects it can manipulate is
-essentially restricted to the elementary types. In particular, it must only
-contain code to which pragma Restrictions (No_Elaboration_Code) applies.
-
-This pragma is used by GNAT to implement auto-initialization of shared Stand
-Alone Libraries, which provides a related capability without the restrictions
-listed above. Where possible, the use of Stand Alone Libraries is preferable
-to the use of this pragma.
-
-@node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{90}
-@section Pragma Linker_Destructor
-
-
-Syntax:
-
-@example
-pragma Linker_Destructor (procedure_LOCAL_NAME);
-@end example
-
-@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 @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 @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
-@anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{91}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{92}
-@section Pragma Linker_Section
-
-
-Syntax:
-
-@example
-pragma Linker_Section (
-  [Entity  =>] LOCAL_NAME,
-  [Section =>] static_string_EXPRESSION);
-@end example
-
-@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
-@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 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
-which do not already have a linker section assigned. The linker section
-aspect is useful in this case for specifying different linker sections
-for different elements of such an overloaded set.
-
-Note that an empty string specifies that no linker section is specified.
-This is not quite the same as omitting the pragma or aspect, since it
-can be used to specify that one element of an overloaded set of subprograms
-has the default linker section, or that one object of a type for which a
-linker section is specified should has the default linker section.
-
-The compiler normally places library-level entities in standard sections
-depending on the class: procedures and functions generally go in the
-@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
-defer the final layout of the executable to the linker, thus fully working
-at the symbolic level with the compiler.
-
-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 @code{.text}
-section). See also @code{pragma Persistent_BSS}.
-
-@example
---  Example of the use of pragma Linker_Section
-
-package IO_Card is
-  Port_A : Integer;
-  pragma Volatile (Port_A);
-  pragma Linker_Section (Port_A, ".bss.port_a");
-
-  Port_B : Integer;
-  pragma Volatile (Port_B);
-  pragma Linker_Section (Port_B, ".bss.port_b");
-
-  type Port_Type is new Integer with Linker_Section => ".bss";
-  PA : Port_Type with Linker_Section => ".bss.PA";
-  PB : Port_Type; --  ends up in linker section ".bss"
-
-  procedure Q with Linker_Section => "Qsection";
-end IO_Card;
-@end example
-
-@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{93}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{94}
-@section Pragma Lock_Free
-
-
-Syntax:
-This pragma may be specified for protected types or objects. It specifies that
-the implementation of protected operations must be implemented without locks.
-Compilation fails if the compiler cannot generate lock-free code for the
-operations.
-
-The current conditions required to support this pragma are:
-
-
-@itemize *
-
-@item 
-Protected type declarations may not contain entries
-
-@item 
-Protected subprogram declarations may not have nonelementary parameters
-@end itemize
-
-In addition, each protected subprogram body must satisfy:
-
-
-@itemize *
-
-@item 
-May reference only one protected component
-
-@item 
-May not reference nonconstant entities outside the protected subprogram
-scope
-
-@item 
-May not contain address representation items, allocators, or quantified
-expressions
-
-@item 
-May not contain delay, goto, loop, or procedure-call statements
-
-@item 
-May not contain exported and imported entities
-
-@item 
-May not dereferenced access values
-
-@item 
-Function calls and attribute references must be static
-@end itemize
-
-If the Lock_Free aspect is specified to be True for a protected unit
-and the Ceiling_Locking locking policy is in effect, then the run-time
-actions associated with the Ceiling_Locking locking policy (described in
-Ada RM D.3) are not performed when a protected operation of the protected
-unit is executed.
-
-@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{95}
-@section Pragma Loop_Invariant
-
-
-Syntax:
-
-@example
-pragma Loop_Invariant ( boolean_EXPRESSION );
-@end example
-
-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).
-
-@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
-represent a “loop invariant” assertion, i.e. something that is true each
-time through the loop, and which can be used to show that the loop is
-achieving its purpose.
-
-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 @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 @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{96}
-@section Pragma Loop_Optimize
-
-
-Syntax:
-
-@example
-pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@});
-
-OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector
-@end example
-
-This pragma must appear immediately within a loop statement.  It allows the
-programmer to specify optimization hints for the enclosing loop.  The hints
-are not mutually exclusive and can be freely mixed, but not all combinations
-will yield a sensible outcome.
-
-There are five supported optimization hints for a loop:
-
-
-@itemize *
-
-@item 
-Ivdep
-
-The programmer asserts that there are no loop-carried dependencies
-which would prevent consecutive iterations of the loop from being
-executed simultaneously.
-
-@item 
-No_Unroll
-
-The loop must not be unrolled.  This is a strong hint: the compiler will not
-unroll a loop marked with this hint.
-
-@item 
-Unroll
-
-The loop should be unrolled.  This is a weak hint: the compiler will try to
-apply unrolling to this loop preferably to other optimizations, notably
-vectorization, but there is no guarantee that the loop will be unrolled.
-
-@item 
-No_Vector
-
-The loop must not be vectorized.  This is a strong hint: the compiler will not
-vectorize a loop marked with this hint.
-
-@item 
-Vector
-
-The loop should be vectorized.  This is a weak hint: the compiler will try to
-apply vectorization to this loop preferably to other optimizations, notably
-unrolling, but there is no guarantee that the loop will be vectorized.
-@end itemize
-
-These hints do not remove the need to pass the appropriate switches to the
-compiler in order to enable the relevant optimizations, that is to say
-`-funroll-loops' for unrolling and `-ftree-vectorize' for
-vectorization.
-
-@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{97}
-@section Pragma Loop_Variant
-
-
-Syntax:
-
-@example
-pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} );
-LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION
-CHANGE_DIRECTION ::= Increases | Decreases
-@end example
-
-@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
-decrease or increase in successive iterations of the loop. In its simplest
-form, just one expression is specified, whose value must increase or decrease
-on each iteration of the loop.
-
-In a more complex form, multiple arguments can be given which are interpreted
-in a nesting lexicographic manner. For example:
-
-@example
-pragma Loop_Variant (Increases => X, Decreases => Y);
-@end example
-
-specifies that each time through the loop either X increases, or X stays
-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.
-
-@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 @code{Disable} in which case the pragma is not even checked for correct
-syntax.
-
-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 @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{98}
-@section Pragma Machine_Attribute
-
-
-Syntax:
-
-@example
-pragma Machine_Attribute (
-     [Entity         =>] LOCAL_NAME,
-     [Attribute_Name =>] static_string_EXPRESSION
-  [, [Info           =>] static_EXPRESSION @{, static_EXPRESSION@}] );
-@end example
-
-Machine-dependent attributes can be specified for types and/or
-declarations.  This pragma is semantically equivalent to
-@code{__attribute__((@var{attribute_name}))} (if @code{info} is not
-specified) or @code{__attribute__((@var{attribute_name(info})))}
-or @code{__attribute__((@var{attribute_name(info,...})))} in GNU C,
-where `attribute_name' is recognized by the compiler middle-end
-or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro.  Note
-that a string literal for the optional parameter @code{info} or the
-following ones is transformed by default into an identifier,
-which may make this pragma unusable for some attributes.
-For further information see @cite{GNU Compiler Collection (GCC) Internals}.
-
-@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{99}
-@section Pragma Main
-
-
-Syntax:
-
-@example
-pragma Main
- (MAIN_OPTION [, MAIN_OPTION]);
-
-MAIN_OPTION ::=
-  [Stack_Size              =>] static_integer_EXPRESSION
-| [Task_Stack_Size_Default =>] static_integer_EXPRESSION
-| [Time_Slicing_Enabled    =>] static_boolean_EXPRESSION
-@end example
-
-This pragma is provided for compatibility with OpenVMS VAX Systems.  It has
-no effect in GNAT, other than being syntax checked.
-
-@node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9a}
-@section Pragma Main_Storage
-
-
-Syntax:
-
-@example
-pragma Main_Storage
-  (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
-
-MAIN_STORAGE_OPTION ::=
-  [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
-| [TOP_GUARD       =>] static_SIMPLE_EXPRESSION
-@end example
-
-This pragma is provided for compatibility with OpenVMS VAX Systems.  It has
-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 id22}@anchor{9b}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9c}
-@section Pragma Max_Queue_Length
-
-
-Syntax:
-
-@example
-pragma Max_Entry_Queue (static_integer_EXPRESSION);
-@end example
-
-This pragma is used to specify the maximum callers per entry queue for
-individual protected entries and entry families. It accepts a single
-integer (-1 or more) as a parameter and must appear after the declaration of an
-entry.
-
-A value of -1 represents no additional restriction on queue length.
-
-@node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9d}
-@section Pragma No_Body
-
-
-Syntax:
-
-@example
-pragma No_Body;
-@end example
-
-There are a number of cases in which a package spec does not require a body,
-and in fact a body is not permitted. GNAT will not permit the spec to be
-compiled if there is a body around. The pragma No_Body allows you to provide
-a body file, even in a case where no body is allowed. The body file must
-contain only comments and a single No_Body pragma. This is recognized by
-the compiler as indicating that no body is logically present.
-
-This is particularly useful during maintenance when a package is modified in
-such a way that a body needed before is no longer needed. The provision of a
-dummy body with a No_Body pragma ensures that there is no interference from
-earlier versions of the package body.
-
-@node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9e}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{9f}
-@section Pragma No_Caching
-
-
-Syntax:
-
-@example
-pragma No_Caching [ (static_boolean_EXPRESSION) ];
-@end example
-
-For the semantics of this pragma, see the entry for aspect @code{No_Caching} in
-the SPARK 2014 Reference Manual, section 7.1.2.
-
-@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a0}
-@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 id24}@anchor{a1}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a2}
-@section Pragma No_Elaboration_Code_All
-
-
-Syntax:
-
-@example
-pragma No_Elaboration_Code_All [(program_unit_NAME)];
-@end example
-
-This is a program unit pragma (there is also an equivalent aspect of the
-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
-current unit, it must also have the No_Elaboration_Code_All aspect set.
-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{a3}
-@section Pragma No_Heap_Finalization
-
-
-Syntax:
-
-@example
-pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ];
-@end example
-
-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
-@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
-@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 @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 id25}@anchor{a4}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a5}
-@section Pragma No_Inline
-
-
-Syntax:
-
-@example
-pragma No_Inline (NAME @{, NAME@});
-@end example
-
-This pragma suppresses inlining for the callable entity or the instances of
-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 `-gnatn' or
-`-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_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a6}
-@section Pragma No_Return
-
-
-Syntax:
-
-@example
-pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@});
-@end example
-
-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 @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.
-
-One use of this pragma is to identify procedures whose only purpose is to raise
-an exception. Another use of this pragma is to suppress incorrect warnings
-about missing returns in functions, where the last statement of a function
-statement sequence is a call to such a procedure.
-
-Note that in Ada 2005 mode, this pragma is part of the language. It is
-available in all earlier versions of Ada as an implementation-defined
-pragma.
-
-@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a7}
-@section Pragma No_Strict_Aliasing
-
-
-Syntax:
-
-@example
-pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
-@end example
-
-@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
-declared in units to which the pragma applies. 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 @cite{GNAT User’s Guide}.
-
-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 id26}@anchor{a8}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{a9}
-@section Pragma No_Tagged_Streams
-
-
-Syntax:
-
-@example
-pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)];
-@end example
-
-Normally when a tagged type is introduced using a full type declaration,
-part of the processing includes generating stream access routines to be
-used by stream attributes referencing the type (or one of its subtypes
-or derived types). This can involve the generation of significant amounts
-of code which is wasted space if stream routines are not needed for the
-type in question.
-
-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.
-
-There are two forms of the pragma. The form with no arguments must appear
-in a declarative sequence or in the declarations of a package spec. This
-pragma affects all subsequent root tagged types declared in the declaration
-sequence, and specifies that no stream routines be generated. The form with
-an argument (for which there is also a corresponding aspect) specifies a
-single root tagged type for which stream routines are not to be generated.
-
-Once the pragma has been given for a particular root tagged type, all subtypes
-and derived types of this type inherit the pragma automatically, so the effect
-applies to a complete hierarchy (this is necessary to deal with the class-wide
-dispatching versions of the stream routines).
-
-When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously
-applied to a tagged type its Expanded_Name and External_Tag are initialized
-with empty strings. This is useful to avoid exposing entity names at binary
-level but has a negative impact on the debuggability of tagged types.
-
-@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{aa}
-@section Pragma Normalize_Scalars
-
-
-Syntax:
-
-@example
-pragma Normalize_Scalars;
-@end example
-
-This is a language defined pragma which is fully implemented in GNAT.  The
-effect is to cause all scalar objects that are not otherwise initialized
-to be initialized.  The initial values are implementation dependent and
-are as follows:
-
-
-@table @asis
-
-@item `Standard.Character'
-
-Objects whose root type is Standard.Character are initialized to
-Character’Last unless the subtype range excludes NUL (in which case
-NUL is used). This choice will always generate an invalid value if
-one exists.
-
-@item `Standard.Wide_Character'
-
-Objects whose root type is Standard.Wide_Character are initialized to
-Wide_Character’Last unless the subtype range excludes NUL (in which case
-NUL is used). This choice will always generate an invalid value if
-one exists.
-
-@item `Standard.Wide_Wide_Character'
-
-Objects whose root type is Standard.Wide_Wide_Character are initialized to
-the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
-which case NUL is used). This choice will always generate an invalid value if
-one exists.
-
-@item `Integer types'
-
-Objects of an integer type are treated differently depending on whether
-negative values are present in the subtype. If no negative values are
-present, then all one bits is used as the initial value except in the
-special case where zero is excluded from the subtype, in which case
-all zero bits are used. This choice will always generate an invalid
-value if one exists.
-
-For subtypes with negative values present, the largest negative number
-is used, except in the unusual case where this largest negative number
-is in the subtype, and the largest positive number is not, in which case
-the largest positive value is used. This choice will always generate
-an invalid value if one exists.
-
-@item `Floating-Point Types'
-
-Objects of all floating-point types are initialized to all 1-bits. For
-standard IEEE format, this corresponds to a NaN (not a number) which is
-indeed an invalid value.
-
-@item `Fixed-Point Types'
-
-Objects of all fixed-point types are treated as described above for integers,
-with the rules applying to the underlying integer value used to represent
-the fixed-point value.
-
-@item `Modular types'
-
-Objects of a modular type are initialized to all one bits, except in
-the special case where zero is excluded from the subtype, in which
-case all zero bits are used. This choice will always generate an
-invalid value if one exists.
-
-@item `Enumeration types'
-
-Objects of an enumeration type are initialized to all one-bits, i.e., to
-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 id27}@anchor{ab}@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{ac}
-@section Pragma Obsolescent
-
-
-Syntax:
-
-@example
-pragma Obsolescent;
-
-pragma Obsolescent (
-  [Message =>] static_string_EXPRESSION
-[,[Version =>] Ada_05]);
-
-pragma Obsolescent (
-  [Entity  =>] NAME
-[,[Message =>] static_string_EXPRESSION
-[,[Version =>] Ada_05]]);
-@end example
-
-This pragma can occur immediately following a declaration of an entity,
-including the case of a record component. If no Entity argument is present,
-then this declaration is the one to which the pragma applies. If an Entity
-parameter is present, it must either match the name of the entity in this
-declaration, or alternatively, the pragma can immediately follow an enumeration
-type declaration, where the Entity argument names one of the enumeration
-literals.
-
-This pragma is used to indicate that the named entity
-is considered obsolescent and should not be used. Typically this is
-used when an API must be modified by eventually removing or modifying
-existing subprograms or other entities. The pragma can be used at an
-intermediate stage when the entity is still present, but will be
-removed later.
-
-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 @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
-@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 @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 @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 @code{Ada.Characters.Handling}), but may be used anywhere.
-
-The following examples show typical uses of this pragma:
-
-@example
-package p is
-   pragma Obsolescent (p, Message => "use pp instead of p");
-end p;
-
-package q is
-   procedure q2;
-   pragma Obsolescent ("use q2new instead");
-
-   type R is new integer;
-   pragma Obsolescent
-     (Entity  => R,
-      Message => "use RR in Ada 2005",
-      Version => Ada_05);
-
-   type M is record
-      F1 : Integer;
-      F2 : Integer;
-      pragma Obsolescent;
-      F3 : Integer;
-   end record;
-
-   type E is (a, bc, 'd', quack);
-   pragma Obsolescent (Entity => bc)
-   pragma Obsolescent (Entity => 'd')
-
-   function "+"
-     (a, b : character) return character;
-   pragma Obsolescent (Entity => "+");
-end;
-@end example
-
-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 @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{ad}
-@section Pragma Optimize_Alignment
-
-
-@geindex Alignment
-@geindex default settings
-
-Syntax:
-
-@example
-pragma Optimize_Alignment (TIME | SPACE | OFF);
-@end example
-
-This is a configuration pragma which affects the choice of default alignments
-for types and objects where no alignment is explicitly specified. There is a
-time/space trade-off in the selection of these values. Large alignments result
-in more efficient code, at the expense of larger data space, since sizes have
-to be increased to match these alignments. Smaller alignments save space, but
-the access code is slower. The normal choice of default alignments for types
-and individual alignment promotions for objects (which is what you get if you
-do not use this pragma, or if you use an argument of OFF), tries to balance
-these two requirements.
-
-Specifying SPACE causes smaller default alignments to be chosen in two cases.
-First any packed record is given an alignment of 1. Second, if a size is given
-for the type, then the alignment is chosen to avoid increasing this size. For
-example, consider:
-
-@example
-type R is record
-   X : Integer;
-   Y : Character;
-end record;
-
-for R'Size use 5*8;
-@end example
-
-In the default mode, this type gets an alignment of 4, so that access to the
-Integer field X are efficient. But this means that objects of the type end up
-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 @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
-whose length depends on a discriminant), has a pragma Pack, then it is not
-in general possible to set the alignment of such a record to one, so the
-pragma is ignored in this case (with a warning).
-
-Specifying SPACE also disables alignment promotions for standalone objects,
-which occur when the compiler increases the alignment of a specific object
-without changing the alignment of its type.
-
-Specifying SPACE also disables component reordering in unpacked record types,
-which can result in larger sizes in order to meet alignment requirements.
-
-Specifying TIME causes larger default alignments to be chosen in the case of
-small types with sizes that are not a power of 2. For example, consider:
-
-@example
-type R is record
-   A : Character;
-   B : Character;
-   C : Boolean;
-end record;
-
-pragma Pack (R);
-for R'Size use 17;
-@end example
-
-The default alignment for this record is normally 1, but if this type is
-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.
-
-As noted above, this is a configuration pragma, and there is a requirement
-that all units in a partition be compiled with a consistent setting of the
-optimization setting. This would normally be achieved by use of a configuration
-pragma file containing the appropriate setting. The exception to this rule is
-that units with an explicit configuration pragma in the same file as the source
-unit are excluded from the consistency check, as are all predefined units. The
-latter are compiled by default in pragma Optimize_Alignment (Off) mode if no
-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{ae}
-@section Pragma Ordered
-
-
-Syntax:
-
-@example
-pragma Ordered (enumeration_first_subtype_LOCAL_NAME);
-@end example
-
-Most enumeration types are from a conceptual point of view unordered.
-For example, consider:
-
-@example
-type Color is (Red, Blue, Green, Yellow);
-@end example
-
-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.
-
-For unordered enumeration types, it is generally a good idea if
-clients avoid comparisons (other than equality or inequality) and
-explicit ranges. (A `client' is a unit where the type is referenced,
-other than the unit where the type is declared, its body, and its subunits.)
-For example, if code buried in some client says:
-
-@example
-if Current_Color < Yellow then ...
-if Current_Color in Blue .. Green then ...
-@end example
-
-then the client code is relying on the order, which is undesirable.
-It makes the code hard to read and creates maintenance difficulties if
-entries have to be added to the enumeration type. Instead,
-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 @code{Color}:
-
-@example
-subtype RBG is Color range Red .. Green;
-@end example
-
-and then the client could write:
-
-@example
-if Current_Color in RBG then ...
-if Current_Color = Blue or Current_Color = Green then ...
-@end example
-
-However, some enumeration types are legitimately ordered from a conceptual
-point of view. For example, if you declare:
-
-@example
-type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
-@end example
-
-then the ordering imposed by the language is reasonable, and
-clients can depend on it, writing for example:
-
-@example
-if D in Mon .. Fri then ...
-if D < Wed then ...
-@end example
-
-The pragma `Ordered' is provided to mark enumeration types that
-are conceptually ordered, alerting the reader that clients may depend
-on the ordering. GNAT provides a pragma to mark enumerations as ordered
-rather than one to mark them as unordered, since in our experience,
-the great majority of enumeration types are conceptually unordered.
-
-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 @code{Ordered} in package @code{Standard}.
-
-Normally pragma @code{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 @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
-template can be instantiated for both cases), so we never generate warnings
-for the case of generic enumerated types.
-
-For additional information please refer to the description of the
-`-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{af}
-@section Pragma Overflow_Mode
-
-
-Syntax:
-
-@example
-pragma Overflow_Mode
- (  [General    =>] MODE
-  [,[Assertions =>] MODE]);
-
-MODE ::= STRICT | MINIMIZED | ELIMINATED
-@end example
-
-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 @code{General} parameter is present,
-the given mode applies to all expressions. If both parameters are present,
-the @code{General} mode applies to expressions outside assertions, and
-the @code{Eliminated} mode applies to expressions within assertions.
-
-The case of the @code{MODE} parameter is ignored,
-so @code{MINIMIZED}, @code{Minimized} and
-@code{minimized} all have the same effect.
-
-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 @code{Suppress (Overflow_Check)} suppresses
-overflow checking, but does not affect the overflow mode.
-
-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{b0}
-@section Pragma Overriding_Renamings
-
-
-@geindex Rational profile
-
-@geindex Rational compatibility
-
-Syntax:
-
-@example
-pragma Overriding_Renamings;
-@end example
-
-This is a GNAT configuration pragma to simplify porting
-legacy code accepted by the Rational
-Ada compiler. In the presence of this pragma, a renaming declaration that
-renames an inherited operation declared in the same scope is legal if selected
-notation is used as in:
-
-@example
-pragma Overriding_Renamings;
-...
-package R is
-  function F (..);
-  ...
-  function F (..) renames R.F;
-end R;
-@end example
-
-even though
-RM 8.3 (15) stipulates that an overridden operation is not visible within the
-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{b1}
-@section Pragma Partition_Elaboration_Policy
-
-
-Syntax:
-
-@example
-pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER);
-
-POLICY_IDENTIFIER ::= Concurrent | Sequential
-@end example
-
-This pragma is standard in Ada 2005, but is available in all earlier
-versions of Ada as an implementation-defined pragma.
-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 id28}@anchor{b2}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b3}
-@section Pragma Part_Of
-
-
-Syntax:
-
-@example
-pragma Part_Of (ABSTRACT_STATE);
-
-ABSTRACT_STATE ::= NAME
-@end example
-
-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{b4}
-@section Pragma Passive
-
-
-Syntax:
-
-@example
-pragma Passive [(Semaphore | No)];
-@end example
-
-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
-@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 @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).
-
-For more information on the subject of passive tasks, see the section
-‘Passive Task Optimization’ in the GNAT Users Guide.
-
-@node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b5}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b6}
-@section Pragma Persistent_BSS
-
-
-Syntax:
-
-@example
-pragma Persistent_BSS [(LOCAL_NAME)]
-@end example
-
-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
-and whose type is potentially persistent. If no argument is given, then
-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,
-non-discriminated record, all of whose components have no explicit
-initialization and are themselves of a potentially persistent type,
-or an array, all of whose constraints are static, and whose component
-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 @code{pragma Linker_Section}.
-
-@node Pragma Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b7}
-@section Pragma Post
-
-
-@geindex Post
-
-@geindex Checks
-@geindex postconditions
-
-Syntax:
-
-@example
-pragma Post (Boolean_Expression);
-@end example
-
-The @code{Post} pragma is intended to be an exact replacement for
-the language-defined
-@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
-appear at the start of the declarations in a subprogram body
-(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{b8}
-@section Pragma Postcondition
-
-
-@geindex Postcondition
-
-@geindex Checks
-@geindex postconditions
-
-Syntax:
-
-@example
-pragma Postcondition (
-   [Check   =>] Boolean_Expression
- [,[Message =>] String_Expression]);
-@end example
-
-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
-implicit returns at the end of procedure bodies and associated
-exception handlers).
-
-In addition, the boolean expression which is the condition which
-must be true may contain references to function’Result in the case
-of a function to refer to the returned value.
-
-@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
-postconditions, or appear before the postcondition in the
-declaration sequence in a subprogram body). In the case of a
-postcondition appearing after a subprogram declaration, the
-formal arguments of the subprogram are visible, and can be
-referenced in the postcondition expressions.
-
-The postconditions are collected and automatically tested just
-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 @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
-if they represent functional aspects which make sense to the client.
-For example we might have:
-
-@example
-function Direction return Integer;
-pragma Postcondition
- (Direction'Result = +1
-    or else
-  Direction'Result = -1);
-@end example
-
-which serves to document that the result must be +1 or -1, and
-will test that this is the case at run time if postcondition
-checking is active.
-
-Postconditions within the subprogram body can be used to
-check that some internal aspect of the implementation,
-not visible to the client, is operating as expected.
-For instance if a square root routine keeps an internal
-counter of the number of times it is called, then we
-might have the following postcondition:
-
-@example
-Sqrt_Calls : Natural := 0;
-
-function Sqrt (Arg : Float) return Float is
-  pragma Postcondition
-    (Sqrt_Calls = Sqrt_Calls'Old + 1);
-  ...
-end Sqrt
-@end example
-
-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.
-
-Note that postconditions are only checked on normal returns
-from the subprogram. If an abnormal return results from
-raising an exception, then the postconditions are not checked.
-
-If a postcondition fails, then the exception
-@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
-the form “Postcondition failed at file_name:line”. The
-exception is raised in the context of the subprogram
-body, so it is possible to catch postcondition failures
-within the subprogram body itself.
-
-Within a package spec, normal visibility rules
-in Ada would prevent forward references within a
-postcondition pragma to functions defined later in
-the same package. This would introduce undesirable
-ordering constraints. To avoid this problem, all
-postcondition pragmas are analyzed at the end of
-the package spec, allowing forward references.
-
-The following example shows that this even allows
-mutually recursive postconditions as in:
-
-@example
-package Parity_Functions is
-   function Odd  (X : Natural) return Boolean;
-   pragma Postcondition
-     (Odd'Result =
-        (x = 1
-          or else
-        (x /= 0 and then Even (X - 1))));
-
-   function Even (X : Natural) return Boolean;
-   pragma Postcondition
-     (Even'Result =
-        (x = 0
-          or else
-        (x /= 1 and then Odd (X - 1))));
-
-end Parity_Functions;
-@end example
-
-There are no restrictions on the complexity or form of
-conditions used within @code{Postcondition} pragmas.
-The following example shows that it is even possible
-to verify performance behavior.
-
-@example
-package Sort is
-
-   Performance : constant Float;
-   --  Performance constant set by implementation
-   --  to match target architecture behavior.
-
-   procedure Treesort (Arg : String);
-   --  Sorts characters of argument using N*logN sort
-   pragma Postcondition
-     (Float (Clock - Clock'Old) <=
-        Float (Arg'Length) *
-        log (Float (Arg'Length)) *
-        Performance);
-end Sort;
-@end example
-
-Note: postcondition pragmas associated with subprograms that are
-marked as Inline_Always, or those marked as Inline with front-end
-inlining (-gnatN option set) are accepted and legality-checked
-by the compiler, but are ignored at run-time even if postcondition
-checking is enabled.
-
-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 @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 Pre,Pragma Postcondition,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{b9}
-@section Pragma Post_Class
-
-
-@geindex Post
-
-@geindex Checks
-@geindex postconditions
-
-Syntax:
-
-@example
-pragma Post_Class (Boolean_Expression);
-@end example
-
-The @code{Post_Class} pragma is intended to be an exact replacement for
-the language-defined
-@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 @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 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 @code{Post'Class}, not
-@code{Post_Class}.
-
-@node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{ba}
-@section Pragma Pre
-
-
-@geindex Pre
-
-@geindex Checks
-@geindex preconditions
-
-Syntax:
-
-@example
-pragma Pre (Boolean_Expression);
-@end example
-
-The @code{Pre} pragma is intended to be an exact replacement for
-the language-defined
-@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
-appear at the start of the declarations in a subprogram body
-(preceded only by other pragmas).
-
-@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bb}
-@section Pragma Precondition
-
-
-@geindex Preconditions
-
-@geindex Checks
-@geindex preconditions
-
-Syntax:
-
-@example
-pragma Precondition (
-   [Check   =>] Boolean_Expression
- [,[Message =>] String_Expression]);
-@end example
-
-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
-cannot be used within the precondition expression.
-
-Otherwise, the placement and visibility rules are identical to those
-described for postconditions. The following is an example of use
-within a package spec:
-
-@example
-package Math_Functions is
-   ...
-   function Sqrt (Arg : Float) return Float;
-   pragma Precondition (Arg >= 0.0)
-   ...
-end Math_Functions;
-@end example
-
-@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
-postconditions, or appear before the postcondition in the
-declaration sequence in a subprogram body).
-
-Note: precondition pragmas associated with subprograms that are
-marked as Inline_Always, or those marked as Inline with front-end
-inlining (-gnatN option set) are accepted and legality-checked
-by the compiler, but are ignored at run-time even if precondition
-checking is enabled.
-
-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 @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 id30}@anchor{bc}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{bd}
-@section Pragma Predicate
-
-
-Syntax:
-
-@example
-pragma Predicate
-  ([Entity =>] type_LOCAL_NAME,
-   [Check  =>] EXPRESSION);
-@end example
-
-This pragma (available in all versions of Ada in GNAT) encompasses both
-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 @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
-
-@example
-type R is range 1 .. 10;
-subtype S is R;
-pragma Predicate (Entity => S, Check => S not in 4 .. 6);
-subtype Q is R
-pragma Predicate (Entity => Q, Check => F(Q) or G(Q));
-@end example
-
-the effect is identical to the following Ada 2012 code:
-
-@example
-type R is range 1 .. 10;
-subtype S is R with
-  Static_Predicate => S not in 4 .. 6;
-subtype Q is R with
-  Dynamic_Predicate => F(Q) or G(Q);
-@end example
-
-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
-corresponding aspects is to allow a program to be written
-using the pragmas, and then compiled with a compiler that
-will ignore the pragmas. That doesn’t work in the case of
-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
-@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{be}
-@section Pragma Predicate_Failure
-
-
-Syntax:
-
-@example
-pragma Predicate_Failure
-  ([Entity  =>] type_LOCAL_NAME,
-   [Message =>] String_Expression);
-@end example
-
-The @code{Predicate_Failure} pragma is intended to be an exact replacement for
-the language-defined
-@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{bf}
-@section Pragma Preelaborable_Initialization
-
-
-Syntax:
-
-@example
-pragma Preelaborable_Initialization (DIRECT_NAME);
-@end example
-
-This pragma is standard in Ada 2005, but is available in all earlier
-versions of Ada as an implementation-defined pragma.
-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{c0}
-@section Pragma Prefix_Exception_Messages
-
-
-@geindex Prefix_Exception_Messages
-
-@geindex exception
-
-@geindex Exception_Message
-
-Syntax:
-
-@example
-pragma Prefix_Exception_Messages;
-@end example
-
-This is an implementation-defined configuration pragma that affects the
-behavior of raise statements with a message given as a static string
-constant (typically a string literal). In such cases, the string will
-be automatically prefixed by the name of the enclosing entity (giving
-the package and subprogram containing the raise statement). This helps
-to identify where messages are coming from, and this mode is automatic
-for the run-time library.
-
-The pragma has no effect if the message is computed with an expression other
-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
-@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{c1}
-@section Pragma Pre_Class
-
-
-@geindex Pre_Class
-
-@geindex Checks
-@geindex preconditions
-
-Syntax:
-
-@example
-pragma Pre_Class (Boolean_Expression);
-@end example
-
-The @code{Pre_Class} pragma is intended to be an exact replacement for
-the language-defined
-@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 @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 @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{c2}
-@section Pragma Priority_Specific_Dispatching
-
-
-Syntax:
-
-@example
-pragma Priority_Specific_Dispatching (
-   POLICY_IDENTIFIER,
-   first_priority_EXPRESSION,
-   last_priority_EXPRESSION)
-
-POLICY_IDENTIFIER ::=
-   EDF_Across_Priorities            |
-   FIFO_Within_Priorities           |
-   Non_Preemptive_Within_Priorities |
-   Round_Robin_Within_Priorities
-@end example
-
-This pragma is standard in Ada 2005, but is available in all earlier
-versions of Ada as an implementation-defined pragma.
-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{c3}
-@section Pragma Profile
-
-
-Syntax:
-
-@example
-pragma Profile (Ravenscar | Restricted | Rational | Jorvik |
-                GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF );
-@end example
-
-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. @code{Ravenscar} is standard in Ada 2005.
-@code{Jorvik} is standard in Ada 202x.
-The other possibilities (@code{Restricted}, @code{Rational},
-@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF})
-are implementation-defined.  @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}.
-
-The set of configuration pragmas is defined in the following sections.
-
-
-@itemize *
-
-@item 
-Pragma Profile (Ravenscar)
-
-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:
-
-
-@itemize *
-
-@item 
-@code{Task_Dispatching_Policy (FIFO_Within_Priorities)}
-
-[RM D.2.2] Tasks are dispatched following a preemptive
-priority-ordered scheduling policy.
-
-@item 
-@code{Locking_Policy (Ceiling_Locking)}
-
-[RM D.3] While tasks and interrupts execute a protected action, they inherit
-the ceiling priority of the corresponding protected object.
-
-@item 
-@code{Detect_Blocking}
-
-This pragma forces the detection of potentially blocking operations within a
-protected operation, and to raise Program_Error if that happens.
-@end itemize
-
-plus the following set of restrictions:
-
-
-@itemize *
-
-@item 
-@code{Max_Entry_Queue_Length => 1}
-
-No task can be queued on a protected entry.
-
-@item 
-@code{Max_Protected_Entries => 1}
-
-@item 
-@code{Max_Task_Entries => 0}
-
-No rendezvous statements are allowed.
-
-@item 
-@code{No_Abort_Statements}
-
-@item 
-@code{No_Dynamic_Attachment}
-
-@item 
-@code{No_Dynamic_Priorities}
-
-@item 
-@code{No_Implicit_Heap_Allocations}
-
-@item 
-@code{No_Local_Protected_Objects}
-
-@item 
-@code{No_Local_Timing_Events}
-
-@item 
-@code{No_Protected_Type_Allocators}
-
-@item 
-@code{No_Relative_Delay}
-
-@item 
-@code{No_Requeue_Statements}
-
-@item 
-@code{No_Select_Statements}
-
-@item 
-@code{No_Specific_Termination_Handlers}
-
-@item 
-@code{No_Task_Allocators}
-
-@item 
-@code{No_Task_Hierarchy}
-
-@item 
-@code{No_Task_Termination}
-
-@item 
-@code{Simple_Barriers}
-@end itemize
-
-The Ravenscar profile also includes the following restrictions that specify
-that there are no semantic dependencies on the corresponding predefined
-packages:
-
-
-@itemize *
-
-@item 
-@code{No_Dependence => Ada.Asynchronous_Task_Control}
-
-@item 
-@code{No_Dependence => Ada.Calendar}
-
-@item 
-@code{No_Dependence => Ada.Execution_Time.Group_Budget}
-
-@item 
-@code{No_Dependence => Ada.Execution_Time.Timers}
-
-@item 
-@code{No_Dependence => Ada.Task_Attributes}
-
-@item 
-@code{No_Dependence => System.Multiprocessors.Dispatching_Domains}
-@end itemize
-
-This set of configuration pragmas and restrictions correspond to the
-definition of the ‘Ravenscar Profile’ for limited tasking, devised and
-published by the @cite{International Real-Time Ada Workshop@comma{} 1997}.
-A description is also available at
-@indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}.
-
-The original definition of the profile was revised at subsequent IRTAW
-meetings. It has been included in the ISO
-@cite{Guide for the Use of the Ada Programming Language in High Integrity Systems},
-and was made part of the Ada 2005 standard.
-The formal definition given by
-the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and
-AI-305) available at
-@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and
-@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}.
-
-The above set is a superset of the restrictions provided by pragma
-@code{Profile (Restricted)}, it includes six additional restrictions
-(@code{Simple_Barriers}, @code{No_Select_Statements},
-@code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
-@code{No_Relative_Delay} and @code{No_Task_Termination}).  This means
-that pragma @code{Profile (Ravenscar)}, like the pragma
-@code{Profile (Restricted)},
-automatically causes the use of a simplified,
-more efficient version of the tasking run-time library.
-
-@item 
-Pragma Profile (Jorvik)
-
-@code{Jorvik} is the new profile added to the Ada 202x draft standard,
-previously implemented under the name @code{GNAT_Extended_Ravenscar}.
-
-The @code{No_Implicit_Heap_Allocations} restriction has been replaced
-by @code{No_Implicit_Task_Allocations} and
-@code{No_Implicit_Protected_Object_Allocations}.
-
-The @code{Simple_Barriers} restriction has been replaced by
-@code{Pure_Barriers}.
-
-The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and
-@code{No_Relative_Delay} restrictions have been removed.
-
-Details on the rationale for @code{Jorvik} and implications for use may be
-found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz,
-T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies – Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science,
-Number 10300.
-
-@item 
-Pragma Profile (GNAT_Ravenscar_EDF)
-
-This profile corresponds to the Ravenscar profile but using
-EDF_Across_Priority as the Task_Scheduling_Policy.
-
-@item 
-Pragma Profile (Restricted)
-
-This profile corresponds to the GNAT restricted run time. It
-establishes the following set of restrictions:
-
-
-@itemize *
-
-@item 
-@code{No_Abort_Statements}
-
-@item 
-@code{No_Entry_Queue}
-
-@item 
-@code{No_Task_Hierarchy}
-
-@item 
-@code{No_Task_Allocators}
-
-@item 
-@code{No_Dynamic_Priorities}
-
-@item 
-@code{No_Terminate_Alternatives}
-
-@item 
-@code{No_Dynamic_Attachment}
-
-@item 
-@code{No_Protected_Type_Allocators}
-
-@item 
-@code{No_Local_Protected_Objects}
-
-@item 
-@code{No_Requeue_Statements}
-
-@item 
-@code{No_Task_Attributes_Package}
-
-@item 
-@code{Max_Asynchronous_Select_Nesting =  0}
-
-@item 
-@code{Max_Task_Entries =  0}
-
-@item 
-@code{Max_Protected_Entries = 1}
-
-@item 
-@code{Max_Select_Alternatives = 0}
-@end itemize
-
-This set of restrictions causes the automatic selection of a simplified
-version of the run time that provides improved performance for the
-limited set of tasking functionality permitted by this set of restrictions.
-
-@item 
-Pragma Profile (Rational)
-
-The Rational profile is intended to facilitate porting legacy code that
-compiles with the Rational APEX compiler, even when the code includes non-
-conforming Ada constructs.  The profile enables the following three pragmas:
-
-
-@itemize *
-
-@item 
-@code{pragma Implicit_Packing}
-
-@item 
-@code{pragma Overriding_Renamings}
-
-@item 
-@code{pragma Use_VADS_Size}
-@end itemize
-@end itemize
-
-@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c4}
-@section Pragma Profile_Warnings
-
-
-Syntax:
-
-@example
-pragma Profile_Warnings (Ravenscar | Restricted | Rational);
-@end example
-
-This is an implementation-defined pragma that is similar in
-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{c5}
-@section Pragma Propagate_Exceptions
-
-
-@geindex Interfacing to C++
-
-Syntax:
-
-@example
-pragma Propagate_Exceptions;
-@end example
-
-This pragma is now obsolete and, other than generating a warning if warnings
-on obsolescent features are enabled, is ignored.
-It is retained for compatibility
-purposes. It used to be used in connection with optimization of
-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{c6}
-@section Pragma Provide_Shift_Operators
-
-
-@geindex Shift operators
-
-Syntax:
-
-@example
-pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME);
-@end example
-
-This pragma can be applied to a first subtype local name that specifies
-either an unsigned or signed type. It has the effect of providing the
-five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic,
-Rotate_Left and Rotate_Right) for the given type. It is similar to
-including the function declarations for these five operators, together
-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{c7}
-@section Pragma Psect_Object
-
-
-Syntax:
-
-@example
-pragma Psect_Object (
-     [Internal =>] LOCAL_NAME,
-  [, [External =>] EXTERNAL_SYMBOL]
-  [, [Size     =>] EXTERNAL_SYMBOL]);
-
-EXTERNAL_SYMBOL ::=
-  IDENTIFIER
-| static_string_EXPRESSION
-@end example
-
-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 id31}@anchor{c8}@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{c9}
-@section Pragma Pure_Function
-
-
-Syntax:
-
-@example
-pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
-@end example
-
-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 @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 identical calls produce the same result in
-the same context. It also means that the function can be used in
-an address clause.
-
-Note that, quite deliberately, there are no static checks to try
-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
-conceptually pure, and can still be optimized, even though it
-modifies a global variable (the count).  Memo functions are another
-example (where a table of previous calls is kept and consulted to
-avoid re-computation).
-
-Note also that the normal rules excluding optimization of subprograms
-in pure units (when parameter types are descended from System.Address,
-or when the full view of a parameter type is limited), do not apply
-for the Pure_Function case. If you explicitly specify Pure_Function,
-the compiler may optimize away calls with identical arguments, and
-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 @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
-@code{System.Address} or a type derived from it.  Such functions are not
-considered pure by default, since the compiler assumes 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 @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 @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 @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 @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{ca}
-@section Pragma Rational
-
-
-Syntax:
-
-@example
-pragma Rational;
-@end example
-
-This pragma is considered obsolescent, but is retained for
-compatibility purposes. It is equivalent to:
-
-@example
-pragma Profile (Rational);
-@end example
-
-@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cb}
-@section Pragma Ravenscar
-
-
-Syntax:
-
-@example
-pragma Ravenscar;
-@end example
-
-This pragma is considered obsolescent, but is retained for
-compatibility purposes. It is equivalent to:
-
-@example
-pragma Profile (Ravenscar);
-@end example
-
-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 id32}@anchor{cc}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{cd}
-@section Pragma Refined_Depends
-
-
-Syntax:
-
-@example
-pragma Refined_Depends (DEPENDENCY_RELATION);
-
-DEPENDENCY_RELATION ::=
-     null
-  | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@})
-
-DEPENDENCY_CLAUSE ::=
-    OUTPUT_LIST =>[+] INPUT_LIST
-  | NULL_DEPENDENCY_CLAUSE
-
-NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST
-
-OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@})
-
-INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@})
-
-OUTPUT ::= NAME | FUNCTION_RESULT
-INPUT  ::= NAME
-
-where FUNCTION_RESULT is a function Result attribute_reference
-@end example
-
-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 id33}@anchor{ce}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{cf}
-@section Pragma Refined_Global
-
-
-Syntax:
-
-@example
-pragma Refined_Global (GLOBAL_SPECIFICATION);
-
-GLOBAL_SPECIFICATION ::=
-     null
-  | (GLOBAL_LIST)
-  | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@})
-
-MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST
-
-MODE_SELECTOR ::= In_Out | Input | Output | Proof_In
-GLOBAL_LIST   ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@})
-GLOBAL_ITEM   ::= NAME
-@end example
-
-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 id34}@anchor{d0}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d1}
-@section Pragma Refined_Post
-
-
-Syntax:
-
-@example
-pragma Refined_Post (boolean_EXPRESSION);
-@end example
-
-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 id35}@anchor{d2}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d3}
-@section Pragma Refined_State
-
-
-Syntax:
-
-@example
-pragma Refined_State (REFINEMENT_LIST);
-
-REFINEMENT_LIST ::=
-  (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@})
-
-REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST
-
-CONSTITUENT_LIST ::=
-     null
-  |  CONSTITUENT
-  | (CONSTITUENT @{, CONSTITUENT@})
-
-CONSTITUENT ::= object_NAME | state_NAME
-@end example
-
-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{d4}
-@section Pragma Relative_Deadline
-
-
-Syntax:
-
-@example
-pragma Relative_Deadline (time_span_EXPRESSION);
-@end example
-
-This pragma is standard in Ada 2005, but is available in all earlier
-versions of Ada as an implementation-defined pragma.
-See Ada 2012 Reference Manual for details.
-
-@node Pragma Remote_Access_Type,Pragma Rename_Pragma,Pragma Relative_Deadline,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d5}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d6}
-@section Pragma Remote_Access_Type
-
-
-Syntax:
-
-@example
-pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME);
-@end example
-
-This pragma appears in the formal part of a generic declaration.
-It specifies an exception to the RM rule from E.2.2(17/2), which forbids
-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 @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
-same generic declaration.
-
-In the generic unit, the formal type is subject to all restrictions
-pertaining to remote access to class-wide types. At instantiation, the
-actual type must be a remote access to class-wide type.
-
-@node Pragma Rename_Pragma,Pragma Restricted_Run_Time,Pragma Remote_Access_Type,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{d7}
-@section Pragma Rename_Pragma
-
-
-@geindex Pragmas
-@geindex synonyms
-
-Syntax:
-
-@example
-pragma Rename_Pragma (
-         [New_Name =>] IDENTIFIER,
-         [Renamed  =>] pragma_IDENTIFIER);
-@end example
-
-This pragma provides a mechanism for supplying new names for existing
-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
-least very similar to) the GNAT implementation defined pragma
-Inline_Always. You could globally replace Inline_Only with Inline_Always.
-
-However, to avoid that source modification, you could instead add a
-configuration pragma:
-
-@example
-pragma Rename_Pragma (
-         New_Name => Inline_Only,
-         Renamed  => Inline_Always);
-@end example
-
-Then GNAT will treat “pragma Inline_Only …” as if you had written
-“pragma Inline_Always …”.
-
-Pragma Inline_Only will not necessarily mean the same thing as the other Ada
-compiler; it’s up to you to make sure the semantics are close enough.
-
-@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Rename_Pragma,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d8}
-@section Pragma Restricted_Run_Time
-
-
-Syntax:
-
-@example
-pragma Restricted_Run_Time;
-@end example
-
-This pragma is considered obsolescent, but is retained for
-compatibility purposes. It is equivalent to:
-
-@example
-pragma Profile (Restricted);
-@end example
-
-which is the preferred method of setting the 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{d9}
-@section Pragma Restriction_Warnings
-
-
-Syntax:
-
-@example
-pragma Restriction_Warnings
-  (restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
-@end example
-
-This pragma allows a series of restriction identifiers to be
-specified (the list of allowed identifiers is the same as for
-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.
-
-One use of this is in situations where you want to know
-about violations of a restriction, but you want to ignore some of
-these violations. Consider this example, where you want to set
-Ada_95 mode and enable style checks, but you want to know about
-any other use of implementation pragmas:
-
-@example
-pragma Restriction_Warnings (No_Implementation_Pragmas);
-pragma Warnings (Off, "violation of No_Implementation_Pragmas");
-pragma Ada_95;
-pragma Style_Checks ("2bfhkM160");
-pragma Warnings (On, "violation of No_Implementation_Pragmas");
-@end example
-
-By including the above lines in a configuration pragmas file,
-the Ada_95 and Style_Checks pragmas are accepted without
-generating a warning, but any other use of implementation
-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{da}
-@section Pragma Reviewable
-
-
-Syntax:
-
-@example
-pragma Reviewable;
-@end example
-
-This pragma is an RM-defined standard pragma, but has no effect on the
-program being compiled, or on the code generated for the program.
-
-To obtain the required output specified in RM H.3.1, the compiler must be
-run with various special switches as follows:
-
-
-@itemize *
-
-@item 
-`Where compiler-generated run-time checks remain'
-
-The switch `-gnatGL'
-may be used to list the expanded code in pseudo-Ada form.
-Runtime checks show up in the listing either as explicit
-checks or operators marked with @{@} to indicate a check is present.
-
-@item 
-`An identification of known exceptions at compile time'
-
-If the program is compiled with `-gnatwa',
-the compiler warning messages will indicate all cases where the compiler
-detects that an exception is certain to occur at run time.
-
-@item 
-`Possible reads of uninitialized variables'
-
-The compiler warns of many such cases, but its output is incomplete.
-@end itemize
-
-
-A supplemental static analysis tool
-may be used to obtain a comprehensive list of all
-possible points at which uninitialized data may be read.
-
-
-@itemize *
-
-@item 
-`Where run-time support routines are implicitly invoked'
-
-In the output from `-gnatGL',
-run-time calls are explicitly listed as calls to the relevant
-run-time routine.
-
-@item 
-`Object code listing'
-
-This may be obtained either by using the `-S' switch,
-or the objdump utility.
-
-@item 
-`Constructs known to be erroneous at compile time'
-
-These are identified by warnings issued by the compiler (use `-gnatwa').
-
-@item 
-`Stack usage information'
-
-Static stack usage data (maximum per-subprogram) can be obtained via the
-`-fstack-usage' switch to the compiler.
-Dynamic stack usage data (per task) can be obtained via the `-u' switch
-to gnatbind
-@end itemize
-
-
-
-@itemize *
-
-@item 
-`Object code listing of entire partition'
-
-This can be obtained by compiling the partition with `-S',
-or by applying objdump
-to all the object files that are part of the partition.
-
-@item 
-`A description of the run-time model'
-
-The full sources of the run-time are available, and the documentation of
-these routines describes how these run-time routines interface to the
-underlying operating system facilities.
-
-@item 
-`Control and data-flow information'
-@end itemize
-
-
-A supplemental static analysis tool
-may be used to obtain complete control and data-flow information, as well as
-comprehensive messages identifying possible problems based on this
-information.
-
-@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{db}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{dc}
-@section Pragma Secondary_Stack_Size
-
-
-Syntax:
-
-@example
-pragma Secondary_Stack_Size (integer_EXPRESSION);
-@end example
-
-This pragma appears within the task definition of a single task declaration
-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
-result, for example a function returning an unconstrained String.
-
-Note this pragma only applies to targets using fixed secondary stacks, like
-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 @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 @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 @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{dd}
-@section Pragma Share_Generic
-
-
-Syntax:
-
-@example
-pragma Share_Generic (GNAME @{, GNAME@});
-
-GNAME ::= generic_unit_NAME | generic_instance_NAME
-@end example
-
-This pragma is provided for compatibility with Dec Ada 83. It has
-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 id38}@anchor{de}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{df}
-@section Pragma Shared
-
-
-This pragma is provided for compatibility with Ada 83. The syntax and
-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{e0}
-@section Pragma Short_Circuit_And_Or
-
-
-Syntax:
-
-@example
-pragma Short_Circuit_And_Or;
-@end example
-
-This configuration pragma causes any occurrence of the AND operator applied to
-operands of type Standard.Boolean to be short-circuited (i.e. the AND operator
-is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This
-may be useful in the context of certification protocols requiring the use of
-short-circuited logical operators. If this configuration pragma occurs locally
-within the file being compiled, it applies only to the file being compiled.
-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{e1}
-@section Pragma Short_Descriptors
-
-
-Syntax:
-
-@example
-pragma Short_Descriptors;
-@end example
-
-This pragma is provided for compatibility with other Ada implementations. It
-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 id39}@anchor{e2}@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e3}
-@section Pragma Simple_Storage_Pool_Type
-
-
-@geindex Storage pool
-@geindex simple
-
-@geindex Simple storage pool
-
-Syntax:
-
-@example
-pragma Simple_Storage_Pool_Type (type_LOCAL_NAME);
-@end example
-
-A type can be established as a ‘simple storage pool type’ by applying
-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 @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
-procedure Allocate
-  (Pool                     : in out SSP;
-   Storage_Address          : out System.Address;
-   Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
-   Alignment                : System.Storage_Elements.Storage_Count);
-
-procedure Deallocate
-  (Pool : in out SSP;
-   Storage_Address          : System.Address;
-   Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
-   Alignment                : System.Storage_Elements.Storage_Count);
-
-function Storage_Size (Pool : SSP)
-  return System.Storage_Elements.Storage_Count;
-@end example
-
-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 @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{e4,,Simple_Storage_Pool}. For example:
-
-@example
-My_Pool : My_Simple_Storage_Pool_Type;
-
-type Acc is access My_Data_Type;
-
-for Acc'Simple_Storage_Pool use My_Pool;
-@end example
-
-See attribute @ref{e4,,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 id40}@anchor{e5}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e6}
-@section Pragma Source_File_Name
-
-
-Syntax:
-
-@example
-pragma Source_File_Name (
-  [Unit_Name     =>] unit_NAME,
-  Spec_File_Name =>  STRING_LITERAL,
-  [Index => INTEGER_LITERAL]);
-
-pragma Source_File_Name (
-  [Unit_Name     =>] unit_NAME,
-  Body_File_Name =>  STRING_LITERAL,
-  [Index => INTEGER_LITERAL]);
-@end example
-
-Use this to override the normal naming convention.  It is a configuration
-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).
-@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 @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
-
-@example
-package B is
-...
-end B;
-
-with B;
-procedure A is
-begin
-   ..
-end A;
-@end example
-
-you could use the following configuration pragmas:
-
-@example
-pragma Source_File_Name
-  (B, Spec_File_Name => "source.ada", Index => 1);
-pragma Source_File_Name
-  (A, Body_File_Name => "source.ada", Index => 2);
-@end example
-
-Note that the @code{gnatname} utility can also be used to generate those
-configuration pragmas.
-
-Another form of the @code{Source_File_Name} pragma allows
-the specification of patterns defining alternative file naming schemes
-to apply to all files.
-
-@example
-pragma Source_File_Name
-  (  [Spec_File_Name  =>] STRING_LITERAL
-   [,[Casing          =>] CASING_SPEC]
-   [,[Dot_Replacement =>] STRING_LITERAL]);
-
-pragma Source_File_Name
-  (  [Body_File_Name  =>] STRING_LITERAL
-   [,[Casing          =>] CASING_SPEC]
-   [,[Dot_Replacement =>] STRING_LITERAL]);
-
-pragma Source_File_Name
-  (  [Subunit_File_Name =>] STRING_LITERAL
-   [,[Casing            =>] CASING_SPEC]
-   [,[Dot_Replacement   =>] STRING_LITERAL]);
-
-CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
-@end example
-
-The first argument is a pattern that contains a single asterisk indicating
-the point at which the unit name is to be inserted in the pattern string
-to form the file name.  The second argument is optional.  If present it
-specifies the casing of the unit name in the resulting file name string.
-The default is lower case.  Finally the third argument allows for systematic
-replacement of any dots in the unit name by the specified string literal.
-
-Note that Source_File_Name pragmas should not be used if you are using
-project files. The reason for this rule is that the project manager is not
-aware of these pragmas, and so other tools that use the project file would not
-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{e7,,Pragma Source_File_Name_Project}.
-
-For more details on the use of the @code{Source_File_Name} pragma, see the
-sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes}
-in the @cite{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 id41}@anchor{e8}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@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{e6,,Pragma Source_File_Name}, and
-most importantly, once pragma Source_File_Name_Project appears,
-no further Source_File_Name pragmas are allowed.
-
-The intention is that Source_File_Name_Project pragmas are always
-generated by the Project Manager in a manner consistent with the naming
-specified in a project file, and when naming is controlled in this manner,
-it is not permissible to attempt to modify this naming scheme using
-Source_File_Name or Source_File_Name_Project pragmas (which would not be
-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{e9}
-@section Pragma Source_Reference
-
-
-Syntax:
-
-@example
-pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
-@end example
-
-This pragma must appear as the first line of a source file.
-@code{integer_literal} is the logical line number of the line following
-the pragma line (for use in error messages and debugging
-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 @code{gnatchop}
-with the `-r' switch, to make sure that the original unchopped
-source file is the one referred to.
-
-The second argument must be a string literal, it cannot be a static
-string expression other than a string literal.  This is because its value
-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 id42}@anchor{ea}@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{eb}
-@section Pragma SPARK_Mode
-
-
-Syntax:
-
-@example
-pragma SPARK_Mode [(On | Off)] ;
-@end example
-
-In general a program can have some parts that are in SPARK 2014 (and
-follow all the rules in the SPARK Reference Manual), and some parts
-that are full Ada 2012.
-
-The SPARK_Mode pragma is used to identify which parts are in SPARK
-2014 (by default programs are in full Ada). The SPARK_Mode pragma can
-be used in the following places:
-
-
-@itemize *
-
-@item 
-As a configuration pragma, in which case it sets the default mode for
-all units compiled with this pragma.
-
-@item 
-Immediately following a library-level subprogram spec
-
-@item 
-Immediately within a library-level package body
-
-@item 
-Immediately following the @code{private} keyword of a library-level
-package spec
-
-@item 
-Immediately following the @code{begin} keyword of a library-level
-package body
-
-@item 
-Immediately within a library-level subprogram body
-@end itemize
-
-Normally a subprogram or package spec/body inherits the current mode
-that is active at the point it is declared. But this can be overridden
-by pragma within the spec or body as above.
-
-The basic consistency rule is that you can’t turn SPARK_Mode back
-@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 @code{Off}, then the body must
-also have SPARK_Mode @code{Off}.
-
-For a package, we have four parts:
-
-
-@itemize *
-
-@item 
-the package public declarations
-
-@item 
-the package private part
-
-@item 
-the body of the package
-
-@item 
-the elaboration code after @code{begin}
-@end itemize
-
-For a package, the rule is that if you explicitly turn SPARK_Mode
-@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 (@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{ec}
-@section Pragma Static_Elaboration_Desired
-
-
-Syntax:
-
-@example
-pragma Static_Elaboration_Desired;
-@end example
-
-This pragma is used to indicate that the compiler should attempt to initialize
-statically the objects declared in the library unit to which the pragma applies,
-when these objects are initialized (explicitly or implicitly) by an aggregate.
-In the absence of this pragma, aggregates in object declarations are expanded
-into assignments and loops, even when the aggregate components are static
-constants. When the aggregate is present the compiler builds a static expression
-that requires no run-time code, so that the initialized object can be placed in
-read-only data space. If the components are not static, or the aggregate has
-more that 100 components, the compiler emits a warning that the pragma cannot
-be obeyed. (See also the restriction No_Implicit_Loops, which supports static
-construction of larger aggregates with static components that include an others
-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{ed}
-@section Pragma Stream_Convert
-
-
-Syntax:
-
-@example
-pragma Stream_Convert (
-  [Entity =>] type_LOCAL_NAME,
-  [Read   =>] function_NAME,
-  [Write  =>] function_NAME);
-@end example
-
-This pragma provides an efficient way of providing user-defined stream
-attributes.  Not only is it simpler to use than specifying the attributes
-directly, but more importantly, it allows the specification to be made in such
-a way that the predefined unit Ada.Streams is not loaded unless it is actually
-needed (i.e. unless the stream attributes are actually used); the use of
-the Stream_Convert pragma adds no overhead at all, unless the stream
-attributes are actually used on the designated type.
-
-The first argument specifies the type for which stream functions are
-provided.  The second parameter provides a function used to read values
-of this type.  It must name a function whose argument type may be any
-subtype, and whose returned type must be the type given as the first
-argument to the pragma.
-
-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 @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 to first call the Write function to convert to the given stream
-type, and then write the result type to the stream.
-
-The Read and Write functions must not be overloaded subprograms.  If necessary
-renamings can be supplied to meet this requirement.
-The usage of this attribute is best illustrated by a simple example, taken
-from the GNAT implementation of package Ada.Strings.Unbounded:
-
-@example
-function To_Unbounded (S : String) return Unbounded_String
-  renames To_Unbounded_String;
-
-pragma Stream_Convert
-  (Unbounded_String, To_Unbounded, To_String);
-@end example
-
-The specifications of the referenced functions, as given in the Ada
-Reference Manual are:
-
-@example
-function To_Unbounded_String (Source : String)
-  return Unbounded_String;
-
-function To_String (Source : Unbounded_String)
-  return String;
-@end example
-
-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 @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 @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{ee}
-@section Pragma Style_Checks
-
-
-Syntax:
-
-@example
-pragma Style_Checks (string_LITERAL | ALL_CHECKS |
-                     On | Off [, LOCAL_NAME]);
-@end example
-
-This pragma is used in conjunction with compiler switches to control the
-built in style checking provided by GNAT.  The compiler switches, if set,
-provide an initial setting for the switches, and this pragma may be used
-to modify these settings, or the settings may be provided entirely by
-the use of the pragma.  This pragma can be used anywhere that a pragma
-is legal, including use as a configuration pragma (including use in
-the @code{gnat.adc} file).
-
-The form with a string literal specifies which style options are to be
-activated.  These are additive, so they apply in addition to any previously
-set style check options.  The codes for the options are the same as those
-used in the `-gnaty' switch to `gcc' or `gnatmake'.
-For example the following two methods can be used to enable
-layout checking:
-
-
-@itemize *
-
-@item 
-@example
-pragma Style_Checks ("l");
-@end example
-
-@item 
-@example
-gcc -c -gnatyl ...
-@end example
-@end itemize
-
-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 (@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 @code{Off} and @code{On}
-can be used to temporarily disable style checks
-as shown in the following example:
-
-@example
-pragma Style_Checks ("k"); -- requires keywords in lower case
-pragma Style_Checks (Off); -- turn off style checks
-NULL;                      -- this will not generate an error message
-pragma Style_Checks (On);  -- turn style checks back on
-NULL;                      -- this will generate an error message
-@end example
-
-Finally the two argument form is allowed only if the first argument is
-@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
-pragma Style_Checks ("r"); -- require consistency of identifier casing
-Arg : Integer;
-Rf1 : Integer := ARG;      -- incorrect, wrong case
-pragma Style_Checks (Off, Arg);
-Rf2 : Integer := ARG;      -- OK, no error
-@end example
-
-@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{ef}
-@section Pragma Subtitle
-
-
-Syntax:
-
-@example
-pragma Subtitle ([Subtitle =>] STRING_LITERAL);
-@end example
-
-This pragma is recognized for compatibility with other Ada compilers
-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{f0}
-@section Pragma Suppress
-
-
-Syntax:
-
-@example
-pragma Suppress (Identifier [, [On =>] Name]);
-@end example
-
-This is a standard pragma, and supports all the check names required in
-the RM. It is included here because GNAT recognizes some additional check
-names that are implementation defined (as permitted by the RM):
-
-
-@itemize *
-
-@item 
-@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 @code{Alignment_Check}
-allows suppression of alignment checks without suppressing other range checks.
-Note that @code{Alignment_Check} is suppressed by default on machines (such as
-the x86) with non-strict alignment.
-
-@item 
-@code{Atomic_Synchronization} can be used to suppress the special memory
-synchronization instructions that are normally generated for access to
-@code{Atomic} variables to ensure correct synchronization between tasks
-that use such variables for synchronization purposes.
-
-@item 
-@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 
-@code{Container_Checks} Can be used to suppress all checks within Ada.Containers
-and instances of its children, including Tampering_Check.
-
-@item 
-@code{Tampering_Check} Can be used to suppress tampering check in the containers.
-
-@item 
-@code{Predicate_Check} can be used to control whether predicate checks are
-active. It is applicable only to predicates for which the policy is
-@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given
-predicate is ignored or checked for the whole program, the use of
-@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 
-@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 @code{Validity_Checks} pragma.
-
-@item 
-Additional check names previously introduced by use of the @code{Check_Name}
-pragma are also allowed.
-@end itemize
-
-Note that pragma Suppress gives the compiler permission to omit
-checks, but does not require the compiler to omit checks. The compiler
-will generate checks if they are essentially free, even when they are
-suppressed. In particular, if the compiler can prove that a certain
-check will necessarily fail, it will generate code to do an
-unconditional ‘raise’, even if checks are suppressed. The compiler
-warns in this case.
-
-Of course, run-time checks are omitted whenever the compiler can prove
-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{f1}
-@section Pragma Suppress_All
-
-
-Syntax:
-
-@example
-pragma Suppress_All;
-@end example
-
-This pragma can appear anywhere within a 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 @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 id43}@anchor{f2}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f3}
-@section Pragma Suppress_Debug_Info
-
-
-Syntax:
-
-@example
-pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME);
-@end example
-
-This pragma can be used to suppress generation of debug information
-for the specified entity. It is intended primarily for use in debugging
-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{f4}
-@section Pragma Suppress_Exception_Locations
-
-
-Syntax:
-
-@example
-pragma Suppress_Exception_Locations;
-@end example
-
-In normal mode, a raise statement for an exception by default generates
-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 @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
-usual. It is not required that this pragma be used consistently within
-a partition, so it is fine to have some units within a partition compiled
-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 id44}@anchor{f5}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f6}
-@section Pragma Suppress_Initialization
-
-
-@geindex Suppressing initialization
-
-@geindex Initialization
-@geindex suppression of
-
-Syntax:
-
-@example
-pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name);
-@end example
-
-Here variable_or_subtype_Name is the name introduced by a type declaration
-or subtype declaration or the name of a variable introduced by an
-object declaration.
-
-In the case of a type or subtype
-this pragma suppresses any implicit or explicit initialization
-for all variables of the given type or subtype,
-including initialization resulting from the use of pragmas
-Normalize_Scalars or Initialize_Scalars.
-
-This is considered a representation item, so it cannot be given after
-the type is frozen. It applies to all subsequent object declarations,
-and also any allocator that creates objects of the type.
-
-If the pragma is given for the first subtype, then it is considered
-to apply to the base type and all its subtypes. If the pragma is given
-for other than a first subtype, then it applies only to the given subtype.
-The pragma may not be given after the type is frozen.
-
-Note that this includes eliminating initialization of discriminants
-for discriminated types, and tags for tagged types. In these cases,
-you will have to use some non-portable mechanism (e.g. address
-overlays or unchecked conversion) to achieve required initialization
-of these fields before accessing any object of the corresponding type.
-
-For the variable case, implicit initialization for the named variable
-is suppressed, just as though its subtype had been given in a pragma
-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{f7}
-@section Pragma Task_Name
-
-
-Syntax
-
-@example
-pragma Task_Name (string_EXPRESSION);
-@end example
-
-This pragma appears within a task definition (like pragma
-@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
-references to task discriminants.  This facility can be used to
-provide different names for different tasks as they are created,
-as illustrated in the example below.
-
-The task name is recorded internally in the run-time structures
-and is accessible to tools like the debugger.  In addition the
-routine @code{Ada.Task_Identification.Image} will return this
-string, with a unique task address appended.
-
-@example
---  Example of the use of pragma Task_Name
-
-with Ada.Task_Identification;
-use Ada.Task_Identification;
-with Text_IO; use Text_IO;
-procedure t3 is
-
-   type Astring is access String;
-
-   task type Task_Typ (Name : access String) is
-      pragma Task_Name (Name.all);
-   end Task_Typ;
-
-   task body Task_Typ is
-      Nam : constant String := Image (Current_Task);
-   begin
-      Put_Line ("-->" & Nam (1 .. 14) & "<--");
-   end Task_Typ;
-
-   type Ptr_Task is access Task_Typ;
-   Task_Var : Ptr_Task;
-
-begin
-   Task_Var :=
-     new Task_Typ (new String'("This is task 1"));
-   Task_Var :=
-     new Task_Typ (new String'("This is task 2"));
-end;
-@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{f8}
-@section Pragma Task_Storage
-
-
-Syntax:
-
-@example
-pragma Task_Storage (
-  [Task_Type =>] LOCAL_NAME,
-  [Top_Guard =>] static_integer_EXPRESSION);
-@end example
-
-This pragma specifies the length of the guard area for tasks.  The guard
-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
-@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 id45}@anchor{f9}@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fa}
-@section Pragma Test_Case
-
-
-@geindex Test cases
-
-Syntax:
-
-@example
-pragma Test_Case (
-   [Name     =>] static_string_Expression
-  ,[Mode     =>] (Nominal | Robustness)
- [, Requires =>  Boolean_Expression]
- [, Ensures  =>  Boolean_Expression]);
-@end example
-
-The @code{Test_Case} pragma allows defining fine-grain specifications
-for use by testing tools.
-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.
-
-@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 @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
-package Math_Functions is
-   ...
-   function Sqrt (Arg : Float) return Float;
-   pragma Test_Case (Name     => "Test 1",
-                     Mode     => Nominal,
-                     Requires => Arg < 10000.0,
-                     Ensures  => Sqrt'Result < 10.0);
-   ...
-end Math_Functions;
-@end example
-
-The meaning of a test case is that there is at least one context where
-@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 @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 id46}@anchor{fb}@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fc}
-@section Pragma Thread_Local_Storage
-
-
-@geindex Task specific storage
-
-@geindex TLS (Thread Local Storage)
-
-@geindex Task_Attributes
-
-Syntax:
-
-@example
-pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME);
-@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” (@code{TLS}). On systems supporting this (which
-include Windows, Solaris, GNU/Linux, and VxWorks), this causes each
-thread (and hence each Ada task) to see a distinct copy of the variable.
-
-The variable must not have default initialization, and if there is
-an explicit initialization, it must be either @code{null} for an
-access variable, a static expression for a scalar variable, or a fully
-static aggregate for a composite type, that is to say, an aggregate all
-of whose components are static, and which does not include packed or
-discriminated components.
-
-This provides a low-level mechanism similar to that provided by
-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 @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{fd}
-@section Pragma Time_Slice
-
-
-Syntax:
-
-@example
-pragma Time_Slice (static_duration_EXPRESSION);
-@end example
-
-For implementations of GNAT on operating systems where it is possible
-to supply a time slice value, this pragma may be used for this purpose.
-It is ignored if it is used in a system that does not allow this control,
-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{fe}
-@section Pragma Title
-
-
-Syntax:
-
-@example
-pragma Title (TITLING_OPTION [, TITLING OPTION]);
-
-TITLING_OPTION ::=
-  [Title    =>] STRING_LITERAL,
-| [Subtitle =>] STRING_LITERAL
-@end example
-
-Syntax checked but otherwise ignored by GNAT.  This is a listing control
-pragma used in DEC Ada 83 implementations to provide a title and/or
-subtitle for the program listing.  The program listing generated by GNAT
-does not have titles or subtitles.
-
-Unlike other pragmas, the full flexibility of named notation is allowed
-for this pragma, i.e., the parameters may be given in any order if named
-notation is used, and named and positional notation can be mixed
-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{ff}
-@section Pragma Type_Invariant
-
-
-Syntax:
-
-@example
-pragma Type_Invariant
-  ([Entity =>] type_LOCAL_NAME,
-   [Check  =>] EXPRESSION);
-@end example
-
-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 @code{Invariant} pragma in that it
-does not permit a string parameter, and it is
-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 id47}@anchor{100}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{101}
-@section Pragma Type_Invariant_Class
-
-
-Syntax:
-
-@example
-pragma Type_Invariant_Class
-  ([Entity =>] type_LOCAL_NAME,
-   [Check  =>] EXPRESSION);
-@end example
-
-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 @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 @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{102}
-@section Pragma Unchecked_Union
-
-
-@geindex Unions in C
-
-Syntax:
-
-@example
-pragma Unchecked_Union (first_subtype_LOCAL_NAME);
-@end example
-
-This pragma is used to specify a representation of a record type that is
-equivalent to a C union. It was introduced as a GNAT implementation defined
-pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this
-pragma, making it language defined, and GNAT fully implements this extended
-version in all language modes (Ada 83, Ada 95, and Ada 2005). For full
-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{103}
-@section Pragma Unevaluated_Use_Of_Old
-
-
-@geindex Attribute Old
-
-@geindex Attribute Loop_Entry
-
-@geindex Unevaluated_Use_Of_Old
-
-Syntax:
-
-@example
-pragma Unevaluated_Use_Of_Old (Error | Warn | Allow);
-@end example
-
-This pragma controls the processing of attributes Old and Loop_Entry.
-If either of these attributes is used in a potentially unevaluated
-expression  (e.g. the then or else parts of an if expression), then
-normally this usage is considered illegal if the prefix of the attribute
-is other than an entity name. The language requires this
-behavior for Old, and GNAT copies the same rule for Loop_Entry.
-
-The reason for this rule is that otherwise, we can have a situation
-where we save the Old value, and this results in an exception, even
-though we might not evaluate the attribute. Consider this example:
-
-@example
-package UnevalOld is
-   K : Character;
-   procedure U (A : String; C : Boolean)  -- ERROR
-     with Post => (if C then A(1)'Old = K else True);
-end;
-@end example
-
-If procedure U is called with a string with a lower bound of 2, and
-C false, then an exception would be raised trying to evaluate A(1)
-on entry even though the value would not be actually used.
-
-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 @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
-@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
-part or package specification. In the latter case it applies to
-uses up to the end of the corresponding statement sequence or
-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{104}
-@section Pragma Unimplemented_Unit
-
-
-Syntax:
-
-@example
-pragma Unimplemented_Unit;
-@end example
-
-If this pragma occurs in a unit that is processed by the compiler, GNAT
-aborts with the message @code{xxx not implemented}, where
-@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.
-
-The abort only happens if code is being generated.  Thus you can use
-specs of unimplemented packages in syntax or semantic checking mode.
-
-@node Pragma Universal_Aliasing,Pragma Unmodified,Pragma Unimplemented_Unit,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{105}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{106}
-@section Pragma Universal_Aliasing
-
-
-Syntax:
-
-@example
-pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
-@end example
-
-@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
-@code{Optimization and Strict Aliasing} in the @cite{GNAT User’s Guide}.
-
-@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Aliasing,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{107}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{108}
-@section Pragma Unmodified
-
-
-@geindex Warnings
-@geindex unmodified
-
-Syntax:
-
-@example
-pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@});
-@end example
-
-This pragma signals that the assignable entities (variables,
-@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
-generated if one of these entities is in fact assigned in the
-same unit as the pragma (or in the corresponding body, or one
-of its subunits).
-
-This is particularly useful for clearly signaling that a particular
-parameter is not modified, even though the spec suggests that it might
-be.
-
-For the variable case, warnings are never given for unreferenced variables
-whose name contains one of the substrings
-@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSE, TMP, TEMP} in any casing. Such names
-are typically to be used in cases where such warnings are expected.
-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 id50}@anchor{109}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10a}
-@section Pragma Unreferenced
-
-
-@geindex Warnings
-@geindex unreferenced
-
-Syntax:
-
-@example
-pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@});
-pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
-@end example
-
-This pragma signals that the entities whose names are listed are
-deliberately not referenced in the current source unit after the
-occurrence of the pragma. This
-suppresses warnings about the
-entities being unreferenced, and in addition a warning will be
-generated if one of these entities is in fact subsequently referenced in the
-same unit as the pragma (or in the corresponding body, or one
-of its subunits).
-
-This is particularly useful for clearly signaling that a particular
-parameter is not referenced in some particular subprogram implementation
-and that this is deliberate. It can also be useful in the case of
-objects declared only for their initialization or finalization side
-effects.
-
-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 @code{do} which
-allows the indication of whether or not accept formals are referenced
-or not to be given individually for each accept statement.
-
-The left hand side of an assignment does not count as a reference for the
-purpose of this pragma. Thus it is fine to assign to an entity for which
-pragma Unreferenced is given. However, use of an entity as an actual for
-an out parameter does count as a reference unless warnings for unread output
-parameters are enabled via @code{-gnatw.o}.
-
-Note that if a warning is desired for all calls to a given subprogram,
-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{ac,,Pragma Obsolescent}.
-
-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 @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
-@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 @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 id51}@anchor{10b}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10c}
-@section Pragma Unreferenced_Objects
-
-
-@geindex Warnings
-@geindex unreferenced
-
-Syntax:
-
-@example
-pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
-@end example
-
-This pragma signals that for the types or subtypes whose names are
-listed, objects which are declared with one of these types or subtypes may
-not be referenced, and if no references appear, no warnings are given.
-
-This is particularly useful for objects which are declared solely for their
-initialization and finalization effect. Such variables are sometimes referred
-to as RAII variables (Resource Acquisition Is Initialization). Using this
-pragma on the relevant type (most typically a limited controlled type), the
-compiler will automatically suppress unwanted warnings about these variables
-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{10d}
-@section Pragma Unreserve_All_Interrupts
-
-
-Syntax:
-
-@example
-pragma Unreserve_All_Interrupts;
-@end example
-
-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 @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 @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 @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 @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 @code{Unreserve_All_Interrupts} pragma.
-
-For a more general facility for controlling what interrupts can be
-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{10e}
-@section Pragma Unsuppress
-
-
-Syntax:
-
-@example
-pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
-@end example
-
-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
-@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
-will compile correctly even if the compiler switches are set to suppress
-checks. For example, in a program that depends on external names of tagged
-types and wants to ensure that the duplicated tag check occurs even if all
-run-time checks are suppressed by a compiler switch, the following
-configuration pragma will ensure this test is not suppressed:
-
-@example
-pragma Unsuppress (Duplicated_Tag_Check);
-@end example
-
-This pragma is standard in Ada 2005. It is available in all earlier versions
-of Ada as an implementation-defined pragma.
-
-Note that in addition to the checks defined in the Ada RM, GNAT recognizes a
-number of implementation-defined check names. See the description of pragma
-@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{10f}
-@section Pragma Use_VADS_Size
-
-
-@geindex Size
-@geindex VADS compatibility
-
-@geindex Rational profile
-
-Syntax:
-
-@example
-pragma Use_VADS_Size;
-@end example
-
-This is a configuration pragma.  In a unit to which it applies, any use
-of the ‘Size attribute is automatically interpreted as a use of the
-‘VADS_Size attribute.  Note that this may result in incorrect semantic
-processing of valid Ada 95 or Ada 2005 programs.  This is intended to aid in
-the handling of existing code which depends on the interpretation of Size
-as implemented in the VADS compiler.  See description of the 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 id52}@anchor{110}@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{111}
-@section Pragma Unused
-
-
-@geindex Warnings
-@geindex unused
-
-Syntax:
-
-@example
-pragma Unused (LOCAL_NAME @{, LOCAL_NAME@});
-@end example
-
-This pragma signals that the assignable entities (variables,
-@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
-assigned, and, in addition, a warning will be generated if one of these
-entities gets assigned or subsequently referenced in the same unit as the
-pragma (in the corresponding body or one of its subunits).
-
-This is particularly useful for clearly signaling that a particular
-parameter is not modified or referenced, even though the spec suggests
-that it might be.
-
-For the variable case, warnings are never given for unreferenced
-variables whose name contains one of the substrings
-@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 @code{pragma Unused} 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{112}
-@section Pragma Validity_Checks
-
-
-Syntax:
-
-@example
-pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
-@end example
-
-This pragma is used in conjunction with compiler switches to control the
-built-in validity checking provided by GNAT.  The compiler switches, if set
-provide an initial setting for the switches, and this pragma may be used
-to modify these settings, or the settings may be provided entirely by
-the use of the pragma.  This pragma can be used anywhere that a pragma
-is legal, including use as a configuration pragma (including use in
-the @code{gnat.adc} file).
-
-The form with a string literal specifies which validity options are to be
-activated.  The validity checks are first set to include only the default
-reference manual settings, and then a string of letters in the string
-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 @code{in} and
-@code{in out} subprogram parameters:
-
-
-@itemize *
-
-@item 
-@example
-pragma Validity_Checks ("im");
-@end example
-
-@item 
-@example
-$ gcc -c -gnatVim ...
-@end example
-@end itemize
-
-The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the @code{gnatVa} switch).
-
-The forms with @code{Off} and @code{On} can be used to temporarily disable
-validity checks as shown in the following example:
-
-@example
-pragma Validity_Checks ("c"); -- validity checks for copies
-pragma Validity_Checks (Off); -- turn off validity checks
-A := B;                       -- B will not be validity checked
-pragma Validity_Checks (On);  -- turn validity checks back on
-A := C;                       -- C will be validity checked
-@end example
-
-@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{113}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{114}
-@section Pragma Volatile
-
-
-Syntax:
-
-@example
-pragma Volatile (LOCAL_NAME);
-@end example
-
-This pragma is defined by the Ada Reference Manual, and the GNAT
-implementation is fully conformant with this definition.  The reason it
-is mentioned in this section is that a pragma of the same name was supplied
-in some Ada 83 compilers, including DEC Ada 83.  The Ada 95 / Ada 2005
-implementation of pragma Volatile is upwards compatible with the
-implementation in DEC Ada 83.
-
-@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{115}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{116}
-@section Pragma Volatile_Full_Access
-
-
-Syntax:
-
-@example
-pragma Volatile_Full_Access (LOCAL_NAME);
-@end example
-
-This is similar in effect to pragma Volatile, except that any reference to the
-object is guaranteed to be done only with instructions that read or write all
-the bits of the object. Furthermore, if the object is of a composite type,
-then any reference to a subcomponent of the object is guaranteed to read
-and/or write all the bits of the object.
-
-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 @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 @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.
-
-@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{117}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{118}
-@section Pragma Volatile_Function
-
-
-Syntax:
-
-@example
-pragma Volatile_Function [ (static_boolean_EXPRESSION) ];
-@end example
-
-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{119}
-@section Pragma Warning_As_Error
-
-
-Syntax:
-
-@example
-pragma Warning_As_Error (static_string_EXPRESSION);
-@end example
-
-This configuration pragma allows the programmer to specify a set
-of warnings that will be treated as errors. Any warning that
-matches the pattern given by the pragma argument will be treated
-as an error. This gives more precise control than -gnatwe,
-which treats warnings as errors.
-
-This pragma can apply to regular warnings (messages enabled by -gnatw)
-and to style warnings (messages that start with “(style)”,
-enabled by -gnaty).
-
-The pattern may contain asterisks, which match zero or more characters
-in the message. For example, you can use @code{pragma Warning_As_Error
-("bits of*unused")} to treat the warning message @code{warning: 960 bits of
-"a" unused} as an error. All characters other than asterisk are treated
-as literal characters in the match. The match is case insensitive; for
-example XYZ matches xyz.
-
-Note that the pattern matches if it occurs anywhere within the warning
-message string (it is not necessary to put an asterisk at the start and
-the end of the message, since this is implied).
-
-Another possibility for the static_string_EXPRESSION which works whether
-or not error tags are enabled (`-gnatw.d') is to use a single
-`-gnatw' tag string, enclosed in brackets,
-as shown in the example below, to treat one category of warnings as errors.
-Note that if you want to treat multiple categories of warnings as errors,
-you can use multiple pragma Warning_As_Error.
-
-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{11a,,Pragma Warnings}.
-By using a single full `-Wxxx' switch in the pragma, such warnings
-can also be treated as errors.
-
-The pragma can appear either in a global configuration pragma file
-(e.g. @code{gnat.adc}), or at the start of a file. Given a global
-configuration pragma file containing:
-
-@example
-pragma Warning_As_Error ("[-gnatwj]");
-@end example
-
-which will treat all obsolescent feature warnings as errors, the
-following program compiles as shown (compile options here are
-`-gnatwa.d -gnatl -gnatj55').
-
-@example
-    1. pragma Warning_As_Error ("*never assigned*");
-    2. function Warnerr return String is
-    3.    X : Integer;
-          |
-       >>> error: variable "X" is never read and
-           never assigned [-gnatwv] [warning-as-error]
-
-    4.    Y : Integer;
-          |
-       >>> warning: variable "Y" is assigned but
-           never read [-gnatwu]
-
-    5. begin
-    6.    Y := 0;
-    7.    return %ABC%;
-                 |
-       >>> error: use of "%" is an obsolescent
-           feature (RM J.2(4)), use """ instead
-           [-gnatwj] [warning-as-error]
-
-    8. end;
-
-8 lines: No errors, 3 warnings (2 treated as errors)
-@end example
-
-Note that this pragma does not affect the set of warnings issued in
-any way, it merely changes the effect of a matching warning if one
-is produced as a result of other warnings options. As shown in this
-example, if the pragma results in a warning being treated as an error,
-the tag is changed from “warning:” to “error:” and the string
-“[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 id56}@anchor{11b}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11a}
-@section Pragma Warnings
-
-
-Syntax:
-
-@example
-pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]);
-
-DETAILS ::= On | Off
-DETAILS ::= On | Off, local_NAME
-DETAILS ::= static_string_EXPRESSION
-DETAILS ::= On | Off, static_string_EXPRESSION
-
-TOOL_NAME ::= GNAT | GNATprove
-
-REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@}
-@end example
-
-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 @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 @code{NAME & ""} to force the
-interpretation as a `static_string_EXPRESSION'.
-
-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 (@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 @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 @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 @code{ON} or @code{OFF}
-may be used as a configuration pragma.
-
-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 @code{Suppress}). This form cannot be used as a configuration
-pragma.
-
-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
-specifying which warnings are to be activated and which deactivated. The
-code for these letters is the same as the string used in the command
-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 @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 @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. 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`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 @code{-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 @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 @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
-@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.
-
-Note that the pattern matches if it occurs anywhere within the warning
-message string (it is not necessary to put an asterisk at the start and
-the end of the message, since this is implied).
-
-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 @code{-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
-as a configuration pragma. The effect is to suppress all warnings (if any)
-that match the pattern string throughout the compilation (or match the
--W switch in the back end case).
-
-The second usage is to suppress a warning locally, and in this case, two
-pragmas must appear in sequence:
-
-@example
-pragma Warnings (Off, Pattern);
-... code where given warning is to be suppressed
-pragma Warnings (On, Pattern);
-@end example
-
-In this usage, the pattern string must match in the Off and On
-pragmas, and (if `-gnatw.w' is given) at least one matching
-warning must be suppressed.
-
-Note: if the ON form is not found, then the effect of the OFF form extends
-until the end of the file (pragma Warnings is purely textual, so its effect
-does not stop at the end of the enclosing scope).
-
-Note: to write a string that will match any warning, use the string
-@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 @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 @code{-gnatd.i} 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.
-
-Note: pragma Warnings does not affect the processing of style messages. See
-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 @code{TOOL_NAME} parameter.
-
-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 @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{11c}
-@section Pragma Weak_External
-
-
-Syntax:
-
-@example
-pragma Weak_External ([Entity =>] LOCAL_NAME);
-@end example
-
-@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 @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.
-
-When a weak symbol is not resolved by the linker, its address is set to
-zero. This is useful in writing interfaces to external modules that may
-or may not be linked in the final executable, for example depending on
-configuration settings.
-
-If a program references at run time an entity to which this pragma has been
-applied, and the corresponding symbol was not resolved at link time, then
-the execution of the program is erroneous. It is not erroneous to take the
-Address of such an entity, for example to guard potential references,
-as shown in the example below.
-
-Some file formats do not support weak symbols so not all target machines
-support this pragma.
-
-@example
---  Example of the use of pragma Weak_External
-
-package External_Module is
-  key : Integer;
-  pragma Import (C, key);
-  pragma Weak_External (key);
-  function Present return boolean;
-end External_Module;
-
-with System; use System;
-package body External_Module is
-  function Present return boolean is
-  begin
-    return key'Address /= System.Null_Address;
-  end Present;
-end External_Module;
-@end example
-
-@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{11d}
-@section Pragma Wide_Character_Encoding
-
-
-Syntax:
-
-@example
-pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL);
-@end example
-
-This pragma specifies the wide character encoding to be used in program
-source text appearing subsequently. It is a configuration pragma, but may
-also be used at any point that a pragma is allowed, and it is permissible
-to have more than one such pragma in a file, allowing multiple encodings
-to appear within the same file.
-
-However, note that the pragma cannot immediately precede the relevant
-wide character, because then the previous encoding will still be in
-effect, causing “illegal character” errors.
-
-The argument can be an identifier or a character literal. In the identifier
-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}.
-
-Note that when the pragma is used within a file, it affects only the
-encoding within that file, and does not affect withed units, specs,
-or subunits.
-
-@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top
-@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{11e}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{11f}@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{120}
-@chapter Implementation Defined Aspects
-
-
-Ada defines (throughout the Ada 2012 reference manual, summarized
-in Annex K) a set of aspects that can be specified for certain entities.
-These language defined aspects are implemented in GNAT in Ada 2012 mode
-and work as described in the Ada 2012 Reference Manual.
-
-In addition, Ada 2012 allows implementations to define additional aspects
-whose meaning is defined by the implementation.  GNAT provides
-a number of these implementation-defined aspects which can be used
-to extend and enhance the functionality of the compiler.  This section of
-the GNAT reference manual describes these additional aspects.
-
-Note that any program using these aspects may not be portable to
-other compilers (although GNAT implements this set of aspects on all
-platforms).  Therefore if portability to other compilers is an important
-consideration, you should minimize the use of these aspects.
-
-Note that for many of these aspects, the effect is essentially similar
-to the use of a pragma or attribute specification with the same name
-applied to the entity. For example, if we write:
-
-@example
-type R is range 1 .. 100
-  with Value_Size => 10;
-@end example
-
-then the effect is the same as:
-
-@example
-type R is range 1 .. 100;
-for R'Value_Size use 10;
-@end example
-
-and if we write:
-
-@example
-type R is new Integer
-  with Shared => True;
-@end example
-
-then the effect is the same as:
-
-@example
-type R is new Integer;
-pragma Shared (R);
-@end example
-
-In the documentation below, such cases are simply marked
-as being boolean aspects equivalent to the corresponding pragma
-or attribute definition clause.
-
-@menu
-* Aspect Abstract_State:: 
-* Aspect Annotate:: 
-* Aspect Async_Readers:: 
-* Aspect Async_Writers:: 
-* Aspect Constant_After_Elaboration:: 
-* Aspect Contract_Cases:: 
-* Aspect Depends:: 
-* Aspect Default_Initial_Condition:: 
-* Aspect Dimension:: 
-* Aspect Dimension_System:: 
-* Aspect Disable_Controlled:: 
-* Aspect Effective_Reads:: 
-* Aspect Effective_Writes:: 
-* Aspect Extensions_Visible:: 
-* Aspect Favor_Top_Level:: 
-* Aspect Ghost:: 
-* Aspect Global:: 
-* Aspect Initial_Condition:: 
-* Aspect Initializes:: 
-* Aspect Inline_Always:: 
-* Aspect Invariant:: 
-* Aspect Invariant’Class:: 
-* Aspect Iterable:: 
-* Aspect Linker_Section:: 
-* Aspect Lock_Free:: 
-* Aspect Max_Queue_Length:: 
-* Aspect No_Caching:: 
-* Aspect No_Elaboration_Code_All:: 
-* Aspect No_Inline:: 
-* Aspect No_Tagged_Streams:: 
-* Aspect No_Task_Parts:: 
-* Aspect Object_Size:: 
-* Aspect Obsolescent:: 
-* Aspect Part_Of:: 
-* Aspect Persistent_BSS:: 
-* Aspect Predicate:: 
-* Aspect Pure_Function:: 
-* Aspect Refined_Depends:: 
-* Aspect Refined_Global:: 
-* Aspect Refined_Post:: 
-* Aspect Refined_State:: 
-* Aspect Relaxed_Initialization:: 
-* Aspect Remote_Access_Type:: 
-* Aspect Secondary_Stack_Size:: 
-* Aspect Scalar_Storage_Order:: 
-* Aspect Shared:: 
-* Aspect Simple_Storage_Pool:: 
-* Aspect Simple_Storage_Pool_Type:: 
-* Aspect SPARK_Mode:: 
-* Aspect Suppress_Debug_Info:: 
-* Aspect Suppress_Initialization:: 
-* Aspect Test_Case:: 
-* Aspect Thread_Local_Storage:: 
-* Aspect Universal_Aliasing:: 
-* Aspect Unmodified:: 
-* Aspect Unreferenced:: 
-* Aspect Unreferenced_Objects:: 
-* Aspect Value_Size:: 
-* Aspect Volatile_Full_Access:: 
-* Aspect Volatile_Function:: 
-* Aspect Warnings:: 
-
-@end menu
-
-@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{121}
-@section Aspect Abstract_State
-
-
-@geindex Abstract_State
-
-This aspect is equivalent to @ref{1e,,pragma Abstract_State}.
-
-@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{122}
-@section Aspect Annotate
-
-
-@geindex Annotate
-
-There are three forms of this aspect (where ID is an identifier,
-and ARG is a general expression),
-corresponding to @ref{29,,pragma Annotate}.
-
-
-@table @asis
-
-@item `Annotate => ID'
-
-Equivalent to @code{pragma Annotate (ID, Entity => Name);}
-
-@item `Annotate => (ID)'
-
-Equivalent to @code{pragma Annotate (ID, Entity => Name);}
-
-@item `Annotate => (ID ,ID @{, ARG@})'
-
-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{123}
-@section Aspect Async_Readers
-
-
-@geindex Async_Readers
-
-This boolean aspect is equivalent to @ref{30,,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{124}
-@section Aspect Async_Writers
-
-
-@geindex Async_Writers
-
-This boolean aspect is equivalent to @ref{32,,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{125}
-@section Aspect Constant_After_Elaboration
-
-
-@geindex Constant_After_Elaboration
-
-This aspect is equivalent to @ref{42,,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{126}
-@section Aspect Contract_Cases
-
-
-@geindex Contract_Cases
-
-This aspect is equivalent to @ref{44,,pragma Contract_Cases}, the sequence
-of clauses being enclosed in parentheses so that syntactically it is an
-aggregate.
-
-@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{127}
-@section Aspect Depends
-
-
-@geindex Depends
-
-This aspect is equivalent to @ref{54,,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{128}
-@section Aspect Default_Initial_Condition
-
-
-@geindex Default_Initial_Condition
-
-This aspect is equivalent to @ref{4e,,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{129}
-@section Aspect Dimension
-
-
-@geindex Dimension
-
-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:
-
-@example
-with Dimension =>
-  ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@})
-
-SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL
-
-DIMENSION_VALUE ::=
-  RATIONAL
-| others               => RATIONAL
-| DISCRETE_CHOICE_LIST => RATIONAL
-
-RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL]
-@end example
-
-This aspect can only be applied to a subtype whose parent type has
-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 @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{12a}
-@section Aspect Dimension_System
-
-
-@geindex Dimension_System
-
-The @code{Dimension_System} aspect is used to define a system of
-dimensions that will be used in subsequent subtype declarations with
-@code{Dimension} aspects that reference this system. The syntax is:
-
-@example
-with Dimension_System => (DIMENSION @{, DIMENSION@});
-
-DIMENSION ::= ([Unit_Name   =>] IDENTIFIER,
-               [Unit_Symbol =>] SYMBOL,
-               [Dim_Symbol  =>] SYMBOL)
-
-SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL
-@end example
-
-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 @code{DIMENSION}
-corresponds to one particular dimension. A maximum of 7 dimensions may
-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. @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 @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:
-
-@example
-type Mks_Type is new Long_Long_Float with
-  Dimension_System => (
-    (Unit_Name => Meter,    Unit_Symbol => 'm',   Dim_Symbol => 'L'),
-    (Unit_Name => Kilogram, Unit_Symbol => "kg",  Dim_Symbol => 'M'),
-    (Unit_Name => Second,   Unit_Symbol => 's',   Dim_Symbol => 'T'),
-    (Unit_Name => Ampere,   Unit_Symbol => 'A',   Dim_Symbol => 'I'),
-    (Unit_Name => Kelvin,   Unit_Symbol => 'K',   Dim_Symbol => '@@'),
-    (Unit_Name => Mole,     Unit_Symbol => "mol", Dim_Symbol => 'N'),
-    (Unit_Name => Candela,  Unit_Symbol => "cd",  Dim_Symbol => 'J'));
-@end example
-
-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).
-
-See section ‘Performing Dimensionality Analysis in GNAT’ in the GNAT Users
-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{12b}
-@section Aspect Disable_Controlled
-
-
-@geindex Disable_Controlled
-
-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{12c}
-@section Aspect Effective_Reads
-
-
-@geindex Effective_Reads
-
-This aspect is equivalent to @ref{59,,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{12d}
-@section Aspect Effective_Writes
-
-
-@geindex Effective_Writes
-
-This aspect is equivalent to @ref{5b,,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{12e}
-@section Aspect Extensions_Visible
-
-
-@geindex Extensions_Visible
-
-This aspect is equivalent to @ref{66,,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{12f}
-@section Aspect Favor_Top_Level
-
-
-@geindex Favor_Top_Level
-
-This boolean aspect is equivalent to @ref{6b,,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{130}
-@section Aspect Ghost
-
-
-@geindex Ghost
-
-This aspect is equivalent to @ref{6f,,pragma Ghost}.
-
-@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{131}
-@section Aspect Global
-
-
-@geindex Global
-
-This aspect is equivalent to @ref{71,,pragma Global}.
-
-@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{132}
-@section Aspect Initial_Condition
-
-
-@geindex Initial_Condition
-
-This aspect is equivalent to @ref{7e,,pragma Initial_Condition}.
-
-@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{133}
-@section Aspect Initializes
-
-
-@geindex Initializes
-
-This aspect is equivalent to @ref{81,,pragma Initializes}.
-
-@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{134}
-@section Aspect Inline_Always
-
-
-@geindex Inline_Always
-
-This boolean aspect is equivalent to @ref{83,,pragma Inline_Always}.
-
-@node Aspect Invariant,Aspect Invariant’Class,Aspect Inline_Always,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{135}
-@section Aspect Invariant
-
-
-@geindex Invariant
-
-This aspect is equivalent to @ref{8a,,pragma Invariant}. It is a
-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{136}
-@section Aspect Invariant’Class
-
-
-@geindex Invariant'Class
-
-This aspect is equivalent to @ref{101,,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{137}
-@section Aspect Iterable
-
-
-@geindex 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 six named components, of which the last three are optional: @code{First},
-@code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}.
-When only the first three components are specified, only the
-@code{for .. in} form of iteration over cursors is available. When @code{Element}
-is specified, both this form and the @code{for .. of} form of iteration over
-elements are available. If the last two components are specified, reverse
-iterations over the container can be specified (analogous to what can be done
-over predefined containers that support the @code{Reverse_Iterator} interface).
-The following is a typical example of use:
-
-@example
-type List is private with
-    Iterable => (First       => First_Cursor,
-                 Next        => Advance,
-                 Has_Element => Cursor_Has_Element
-               [,Element     => Get_Element]
-               [,Last        => Last_Cursor]
-               [,Previous    => Retreat]);
-@end example
-
-
-@itemize *
-
-@item 
-The values of @code{First} and @code{Last} are primitive operations of the
-container type that return a @code{Cursor}, which must be a type declared in
-the container package or visible from it. For example:
-@end itemize
-
-@example
-function First_Cursor (Cont : Container) return Cursor;
-function Last_Cursor  (Cont : Container) return Cursor;
-@end example
-
-
-@itemize *
-
-@item 
-The values of @code{Next} and @code{Previous} are primitive operations of the container type that take
-both a container and a cursor and yield a cursor. For example:
-@end itemize
-
-@example
-function Advance (Cont : Container; Position : Cursor) return Cursor;
-function Retreat (Cont : Container; Position : Cursor) return Cursor;
-@end example
-
-
-@itemize *
-
-@item 
-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
-
-@example
-function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean;
-@end example
-
-
-@itemize *
-
-@item 
-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
-
-@example
-function Get_Element (Cont : Container; Position : Cursor) return Element_Type;
-@end example
-
-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{138}
-@section Aspect Linker_Section
-
-
-@geindex Linker_Section
-
-This aspect is equivalent to @ref{92,,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{139}
-@section Aspect Lock_Free
-
-
-@geindex Lock_Free
-
-This boolean aspect is equivalent to @ref{94,,pragma Lock_Free}.
-
-@node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects
-@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 @ref{9c,,pragma Max_Queue_Length}.
-
-@node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{13b}
-@section Aspect No_Caching
-
-
-@geindex No_Caching
-
-This boolean aspect is equivalent to @ref{9f,,pragma No_Caching}.
-
-@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13c}
-@section Aspect No_Elaboration_Code_All
-
-
-@geindex No_Elaboration_Code_All
-
-This aspect is equivalent to @ref{a2,,pragma No_Elaboration_Code_All}
-for a program unit.
-
-@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{13d}
-@section Aspect No_Inline
-
-
-@geindex No_Inline
-
-This boolean aspect is equivalent to @ref{a5,,pragma No_Inline}.
-
-@node Aspect No_Tagged_Streams,Aspect No_Task_Parts,Aspect No_Inline,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{13e}
-@section Aspect No_Tagged_Streams
-
-
-@geindex No_Tagged_Streams
-
-This aspect is equivalent to @ref{a9,,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 No_Task_Parts,Aspect Object_Size,Aspect No_Tagged_Streams,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-no-task-parts}@anchor{13f}
-@section Aspect No_Task_Parts
-
-
-@geindex No_Task_Parts
-
-Applies to a type. If True, requires that the type and any descendants
-do not have any task parts. The rules for this aspect are the same as
-for the language-defined No_Controlled_Parts aspect (see RM-H.4.1),
-replacing “controlled” with “task”.
-
-If No_Task_Parts is True for a type T, then the compiler can optimize
-away certain tasking-related code that would otherwise be needed
-for T’Class, because descendants of T might contain tasks.
-
-@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Task_Parts,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{140}
-@section Aspect Object_Size
-
-
-@geindex Object_Size
-
-This aspect is equivalent to @ref{141,,attribute Object_Size}.
-
-@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{142}
-@section Aspect Obsolescent
-
-
-@geindex Obsolescent
-
-This aspect is equivalent to @ref{ac,,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{143}
-@section Aspect Part_Of
-
-
-@geindex Part_Of
-
-This aspect is equivalent to @ref{b3,,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{144}
-@section Aspect Persistent_BSS
-
-
-@geindex Persistent_BSS
-
-This boolean aspect is equivalent to @ref{b6,,pragma Persistent_BSS}.
-
-@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{145}
-@section Aspect Predicate
-
-
-@geindex Predicate
-
-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
-@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{146}
-@section Aspect Pure_Function
-
-
-@geindex Pure_Function
-
-This boolean aspect is equivalent to @ref{c9,,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{147}
-@section Aspect Refined_Depends
-
-
-@geindex Refined_Depends
-
-This aspect is equivalent to @ref{cd,,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{148}
-@section Aspect Refined_Global
-
-
-@geindex Refined_Global
-
-This aspect is equivalent to @ref{cf,,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{149}
-@section Aspect Refined_Post
-
-
-@geindex Refined_Post
-
-This aspect is equivalent to @ref{d1,,pragma Refined_Post}.
-
-@node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{14a}
-@section Aspect Refined_State
-
-
-@geindex Refined_State
-
-This aspect is equivalent to @ref{d3,,pragma Refined_State}.
-
-@node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{14b}
-@section Aspect Relaxed_Initialization
-
-
-@geindex Refined_Initialization
-
-For the syntax and semantics of this aspect, see the SPARK 2014 Reference
-Manual, section 6.10.
-
-@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{14c}
-@section Aspect Remote_Access_Type
-
-
-@geindex 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{14d}
-@section Aspect Secondary_Stack_Size
-
-
-@geindex Secondary_Stack_Size
-
-This aspect is equivalent to @ref{dc,,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{14e}
-@section Aspect Scalar_Storage_Order
-
-
-@geindex Scalar_Storage_Order
-
-This aspect is equivalent to a @ref{14f,,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{150}
-@section Aspect Shared
-
-
-@geindex Shared
-
-This boolean aspect is equivalent to @ref{df,,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{151}
-@section Aspect Simple_Storage_Pool
-
-
-@geindex Simple_Storage_Pool
-
-This aspect is equivalent to @ref{e4,,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{152}
-@section Aspect Simple_Storage_Pool_Type
-
-
-@geindex Simple_Storage_Pool_Type
-
-This boolean aspect is equivalent to @ref{e3,,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{153}
-@section Aspect SPARK_Mode
-
-
-@geindex SPARK_Mode
-
-This aspect is equivalent to @ref{eb,,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{154}
-@section Aspect Suppress_Debug_Info
-
-
-@geindex Suppress_Debug_Info
-
-This boolean aspect is equivalent to @ref{f3,,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{155}
-@section Aspect Suppress_Initialization
-
-
-@geindex Suppress_Initialization
-
-This boolean aspect is equivalent to @ref{f6,,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{156}
-@section Aspect Test_Case
-
-
-@geindex Test_Case
-
-This aspect is equivalent to @ref{fa,,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{157}
-@section Aspect Thread_Local_Storage
-
-
-@geindex Thread_Local_Storage
-
-This boolean aspect is equivalent to @ref{fc,,pragma Thread_Local_Storage}.
-
-@node Aspect Universal_Aliasing,Aspect Unmodified,Aspect Thread_Local_Storage,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{158}
-@section Aspect Universal_Aliasing
-
-
-@geindex Universal_Aliasing
-
-This boolean aspect is equivalent to @ref{106,,pragma Universal_Aliasing}.
-
-@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Aliasing,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{159}
-@section Aspect Unmodified
-
-
-@geindex 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{15a}
-@section Aspect Unreferenced
-
-
-@geindex Unreferenced
-
-This boolean aspect is equivalent to @ref{10a,,pragma Unreferenced}.
-
-When using the @code{-gnat2022} switch, this aspect is also supported on formal
-parameters, which is in particular the only form possible for expression
-functions.
-
-@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{15b}
-@section Aspect Unreferenced_Objects
-
-
-@geindex 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{15c}
-@section Aspect Value_Size
-
-
-@geindex Value_Size
-
-This aspect is equivalent to @ref{15d,,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{15e}
-@section Aspect Volatile_Full_Access
-
-
-@geindex Volatile_Full_Access
-
-This boolean aspect is equivalent to @ref{116,,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{15f}
-@section Aspect Volatile_Function
-
-
-@geindex 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{160}
-@section Aspect Warnings
-
-
-@geindex Warnings
-
-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{161}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{162}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}
-@chapter Implementation Defined Attributes
-
-
-Ada defines (throughout the Ada reference manual,
-summarized in Annex K),
-a set of attributes that provide useful additional functionality in all
-areas of the language.  These language defined attributes are implemented
-in GNAT and work as described in the Ada Reference Manual.
-
-In addition, Ada allows implementations to define additional
-attributes whose meaning is defined by the implementation.  GNAT provides
-a number of these implementation-dependent attributes which can be used
-to extend and enhance the functionality of the compiler.  This section of
-the GNAT reference manual describes these additional attributes.  It also
-describes additional implementation-dependent features of standard
-language-defined attributes.
-
-Note that any program using these attributes may not be portable to
-other compilers (although GNAT implements this set of attributes on all
-platforms).  Therefore if portability to other compilers is an important
-consideration, you should minimize the use of these attributes.
-
-@menu
-* Attribute Abort_Signal:: 
-* Attribute Address_Size:: 
-* Attribute Asm_Input:: 
-* Attribute Asm_Output:: 
-* Attribute Atomic_Always_Lock_Free:: 
-* Attribute Bit:: 
-* Attribute Bit_Position:: 
-* Attribute Code_Address:: 
-* Attribute Compiler_Version:: 
-* Attribute Constrained:: 
-* Attribute Default_Bit_Order:: 
-* Attribute Default_Scalar_Storage_Order:: 
-* Attribute Deref:: 
-* Attribute Descriptor_Size:: 
-* Attribute Elaborated:: 
-* Attribute Elab_Body:: 
-* Attribute Elab_Spec:: 
-* Attribute Elab_Subp_Body:: 
-* Attribute Emax:: 
-* Attribute Enabled:: 
-* Attribute Enum_Rep:: 
-* Attribute Enum_Val:: 
-* Attribute Epsilon:: 
-* Attribute Fast_Math:: 
-* Attribute Finalization_Size:: 
-* Attribute Fixed_Value:: 
-* Attribute From_Any:: 
-* Attribute Has_Access_Values:: 
-* Attribute Has_Discriminants:: 
-* Attribute Has_Tagged_Values:: 
-* Attribute Img:: 
-* Attribute Initialized:: 
-* Attribute Integer_Value:: 
-* Attribute Invalid_Value:: 
-* Attribute Iterable:: 
-* Attribute Large:: 
-* Attribute Library_Level:: 
-* Attribute Loop_Entry:: 
-* Attribute Machine_Size:: 
-* Attribute Mantissa:: 
-* Attribute Maximum_Alignment:: 
-* Attribute Max_Integer_Size:: 
-* Attribute Mechanism_Code:: 
-* Attribute Null_Parameter:: 
-* Attribute Object_Size:: 
-* Attribute Old:: 
-* Attribute Passed_By_Reference:: 
-* Attribute Pool_Address:: 
-* Attribute Range_Length:: 
-* Attribute Restriction_Set:: 
-* Attribute Result:: 
-* Attribute Safe_Emax:: 
-* Attribute Safe_Large:: 
-* Attribute Safe_Small:: 
-* Attribute Scalar_Storage_Order:: 
-* Attribute Simple_Storage_Pool:: 
-* Attribute Small:: 
-* Attribute Small_Denominator:: 
-* Attribute Small_Numerator:: 
-* Attribute Storage_Unit:: 
-* Attribute Stub_Type:: 
-* Attribute System_Allocator_Alignment:: 
-* Attribute Target_Name:: 
-* Attribute To_Address:: 
-* Attribute To_Any:: 
-* Attribute Type_Class:: 
-* Attribute Type_Key:: 
-* Attribute TypeCode:: 
-* Attribute Unconstrained_Array:: 
-* Attribute Universal_Literal_String:: 
-* Attribute Unrestricted_Access:: 
-* Attribute Update:: 
-* Attribute Valid_Value:: 
-* Attribute Valid_Scalars:: 
-* Attribute VADS_Size:: 
-* Attribute Value_Size:: 
-* Attribute Wchar_T_Size:: 
-* Attribute Word_Size:: 
-
-@end menu
-
-@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{163}
-@section Attribute Abort_Signal
-
-
-@geindex Abort_Signal
-
-@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
-completely outside the normal semantics of Ada, for a user program to
-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{164}
-@section Attribute Address_Size
-
-
-@geindex Size of `@w{`}Address`@w{`}
-
-@geindex Address_Size
-
-@code{Standard'Address_Size} (@code{Standard} is the only allowed
-prefix) is a static constant giving the number of bits in an
-@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{165}
-@section Attribute Asm_Input
-
-
-@geindex Asm_Input
-
-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,
-(e.g., what kind of register is required).  The second argument is the
-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{166,,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{167}
-@section Attribute Asm_Output
-
-
-@geindex Asm_Output
-
-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
-constraint for the parameter (e.g., what kind of register is
-required).  The second argument is the variable to be updated with 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 @code{No_Output_Operands}.
-@ref{166,,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{168}
-@section Attribute Atomic_Always_Lock_Free
-
-
-@geindex Atomic_Always_Lock_Free
-
-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{169}
-@section Attribute Bit
-
-
-@geindex 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 `universal_integer' and is always a nonnegative number smaller
-than @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
-allocation of a variable to memory).
-
-For an object that is a formal parameter, this attribute applies
-to either the matching actual parameter or to a copy of the
-matching actual parameter.
-
-For an access object the value is zero.  Note that
-@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 @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{16a}
-@section Attribute Bit_Position
-
-
-@geindex Bit_Position
-
-@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 `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{16b}
-@section Attribute Code_Address
-
-
-@geindex Code_Address
-
-@geindex Subprogram address
-
-@geindex Address of subprogram code
-
-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
-an address clause as in the following example:
-
-@example
-procedure K is ...
-
-procedure L;
-for L'Address use K'Address;
-pragma Import (Ada, L);
-@end example
-
-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 @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 @code{Address} value described above.
-For example, the @code{Address} value may reference a subprogram
-descriptor rather than the subprogram itself.
-
-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 @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{16c}
-@section Attribute Compiler_Version
-
-
-@geindex Compiler_Version
-
-@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{16d}
-@section Attribute Constrained
-
-
-@geindex Constrained
-
-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 @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{16e}
-@section Attribute Default_Bit_Order
-
-
-@geindex Big endian
-
-@geindex Little endian
-
-@geindex Default_Bit_Order
-
-@code{Standard'Default_Bit_Order} (@code{Standard} is the only
-allowed 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{16f}
-@section Attribute Default_Scalar_Storage_Order
-
-
-@geindex Big endian
-
-@geindex Little endian
-
-@geindex Default_Scalar_Storage_Order
-
-@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only
-allowed prefix), provides the current value of the default scalar storage
-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{170}
-@section Attribute Deref
-
-
-@geindex Deref
-
-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{171}
-@section Attribute Descriptor_Size
-
-
-@geindex Descriptor
-
-@geindex Dope vector
-
-@geindex Descriptor_Size
-
-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 first element of the array.
-
-@example
-type Unconstr_Array is array (Short_Short_Integer range <>) of Positive;
-Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img);
-@end example
-
-The attribute takes into account any padding due to the alignment of the
-component type. In the example above, the descriptor contains two values
-of type @code{Short_Short_Integer} representing the low and high bound. But,
-since @code{Positive} has an alignment of 4, the size of the descriptor is
-@code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32,
-which yields a size of 32 bits, i.e. including 16 bits of padding.
-
-@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{172}
-@section Attribute Elaborated
-
-
-@geindex Elaborated
-
-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
-in user programs.  The value will always be True once elaboration of all
-units has been completed.  An exception is for units which need no
-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{173}
-@section Attribute Elab_Body
-
-
-@geindex Elab_Body
-
-This attribute can only be applied to a program unit name.  It returns
-the entity for the corresponding elaboration procedure for elaborating
-the body of the referenced unit.  This is used in the main generated
-elaboration procedure by the binder and is not normally used in any
-other context.  However, there may be specialized situations in which it
-is useful to be able to call this elaboration procedure from Ada code,
-e.g., if it is necessary to do selective re-elaboration to fix some
-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{174}
-@section Attribute Elab_Spec
-
-
-@geindex Elab_Spec
-
-This attribute can only be applied to a program unit name.  It returns
-the entity for the corresponding elaboration procedure for elaborating
-the spec of the referenced unit.  This is used in the main
-generated elaboration procedure by the binder and is not normally used
-in any other context.  However, there may be specialized situations in
-which it is useful to be able to call this elaboration procedure from
-Ada code, e.g., if it is necessary to do selective re-elaboration to fix
-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{175}
-@section Attribute Elab_Subp_Body
-
-
-@geindex Elab_Subp_Body
-
-This attribute can only be applied to a library level subprogram
-name and is only allowed in CodePeer mode. It returns the entity
-for the corresponding elaboration procedure for elaborating the body
-of the referenced subprogram unit. This is used in the main generated
-elaboration procedure by the binder in CodePeer mode only and is unrecognized
-otherwise.
-
-@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{176}
-@section Attribute Emax
-
-
-@geindex Ada 83 attributes
-
-@geindex Emax
-
-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{177}
-@section Attribute Enabled
-
-
-@geindex Enabled
-
-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
-@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 @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 @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 @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{178}
-@section Attribute Enum_Rep
-
-
-@geindex Representation of enums
-
-@geindex Enum_Rep
-
-Note that this attribute is now standard in Ada 202x and is available
-as an implementation defined attribute for earlier Ada versions.
-
-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 @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 @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 @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 @code{(<>)} discrete formal arguments in
-a generic unit that can be instantiated with either enumeration types
-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 @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{179}
-@section Attribute Enum_Val
-
-
-@geindex Representation of enums
-
-@geindex Enum_Val
-
-Note that this attribute is now standard in Ada 202x and is available
-as an implementation defined attribute for earlier Ada versions.
-
-For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a
-function with the following spec:
-
-@example
-function S'Enum_Val (Arg : <Universal_Integer>) return S'Base;
-@end 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 @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{17a}
-@section Attribute Epsilon
-
-
-@geindex Ada 83 attributes
-
-@geindex Epsilon
-
-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{17b}
-@section Attribute Fast_Math
-
-
-@geindex Fast_Math
-
-@code{Standard'Fast_Math} (@code{Standard} is the only allowed
-prefix) yields a static Boolean value that is True if pragma
-@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{17c}
-@section Attribute Finalization_Size
-
-
-@geindex Finalization_Size
-
-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 `universal_integer'.
-
-@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{17d}
-@section Attribute Fixed_Value
-
-
-@geindex Fixed_Value
-
-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 @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 @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{17e}
-@section Attribute From_Any
-
-
-@geindex From_Any
-
-This internal attribute is used for the generation of remote subprogram
-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{17f}
-@section Attribute Has_Access_Values
-
-
-@geindex Access values
-@geindex testing for
-
-@geindex Has_Access_Values
-
-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.
-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 access values.
-
-@node Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{180}
-@section Attribute Has_Discriminants
-
-
-@geindex Discriminants
-@geindex testing for
-
-@geindex Has_Discriminants
-
-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 Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{181}
-@section Attribute Has_Tagged_Values
-
-
-@geindex Tagged values
-@geindex testing for
-
-@geindex Has_Tagged_Values
-
-The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a
-Boolean value which is True if the type is a composite type (array or record)
-that is either a tagged type or has a subcomponent that is tagged, and is 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 access values.
-
-@node Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{182}
-@section Attribute Img
-
-
-@geindex Img
-
-The @code{Img} attribute differs from @code{Image} in that, while both can be
-applied directly to an object, @code{Img} cannot be applied to types.
-
-Example usage of the attribute:
-
-@example
-Put_Line ("X = " & X'Img);
-@end example
-
-which has the same meaning as the more verbose:
-
-@example
-Put_Line ("X = " & T'Image (X));
-@end example
-
-where @code{T} is the (sub)type of the object @code{X}.
-
-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
-@code{X'Img} can be renamed as a function-returning-string, or used
-in an instantiation as a function parameter.
-
-@node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{183}
-@section Attribute Initialized
-
-
-@geindex Initialized
-
-For the syntax and semantics of this attribute, see the SPARK 2014 Reference
-Manual, section 6.10.
-
-@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{184}
-@section Attribute Integer_Value
-
-
-@geindex Integer_Value
-
-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 @code{V}, such that:
-
-@example
-Arg = V * T'Small
-@end example
-
-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
-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
-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{185}
-@section Attribute Invalid_Value
-
-
-@geindex Invalid_Value
-
-For every scalar type S, S’Invalid_Value returns an undefined value of the
-type. If possible this value is an invalid representation for the type. The
-value returned is identical to the value used to initialize an otherwise
-uninitialized value of the type if pragma Initialize_Scalars is used,
-including the ability to modify the value with the binder -Sxx flag and
-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{186}
-@section Attribute Iterable
-
-
-@geindex 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{187}
-@section Attribute Large
-
-
-@geindex Ada 83 attributes
-
-@geindex Large
-
-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 Loop_Entry,Attribute Large,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{188}
-@section Attribute Library_Level
-
-
-@geindex Library_Level
-
-@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 instantiation, the name of the generic unit denotes the
-instance, which means that this attribute can be used to test
-if a generic is instantiated at the library level, as shown
-in this example:
-
-@example
-generic
-  ...
-package Gen is
-  pragma Compile_Time_Error
-    (not Gen'Library_Level,
-     "Gen can only be instantiated at library level");
-  ...
-end Gen;
-@end example
-
-@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Library_Level,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{189}
-@section Attribute Loop_Entry
-
-
-@geindex Loop_Entry
-
-Syntax:
-
-@example
-X'Loop_Entry [(loop_name)]
-@end example
-
-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
-@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 @code{Loop_Entry} attribute can only occur within an @code{Assert},
-@code{Assert_And_Cut}, @code{Assume}, @code{Loop_Variant} or @code{Loop_Invariant} pragma.
-In addition, such a pragma must be 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.
-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 @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{18a}
-@section Attribute Machine_Size
-
-
-@geindex Machine_Size
-
-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{18b}
-@section Attribute Mantissa
-
-
-@geindex Ada 83 attributes
-
-@geindex Mantissa
-
-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 Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{18c}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{18d}
-@section Attribute Maximum_Alignment
-
-
-@geindex Alignment
-@geindex maximum
-
-@geindex Maximum_Alignment
-
-@code{Standard'Maximum_Alignment} (@code{Standard} is the only
-allowed 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 Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{18e}
-@section Attribute Max_Integer_Size
-
-
-@geindex Max_Integer_Size
-
-@code{Standard'Max_Integer_Size} (@code{Standard} is the only allowed
-prefix) provides the size of the largest supported integer type for
-the target. The result is a static constant.
-
-@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{18f}
-@section Attribute Mechanism_Code
-
-
-@geindex Return values
-@geindex passing mechanism
-
-@geindex Parameters
-@geindex passing mechanism
-
-@geindex Mechanism_Code
-
-@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 `n' (a static integer value, with 1
-meaning the first parameter) of subprogram @code{subprog}.  The code returned is:
-
-
-@table @asis
-
-@item `1'
-
-by copy (value)
-
-@item `2'
-
-by reference
-@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{190}
-@section Attribute Null_Parameter
-
-
-@geindex Zero address
-@geindex passing
-
-@geindex Null_Parameter
-
-A reference @code{T'Null_Parameter} denotes an imaginary object of
-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.
-
-The identity of the object is represented by the address zero in the
-argument list, independent of the passing mechanism (explicit or
-default).
-
-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 @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{141}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{191}
-@section Attribute Object_Size
-
-
-@geindex Size
-@geindex used for objects
-
-@geindex 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,
-@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
-type Rec is record
-   I : Integer;
-   C : Character;
-end record;
-@end example
-
-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).
-
-If the alignment of the above record is specified to be 1, then the
-object size will be 40 (5 bytes). This is true by default, and also
-an object size of 40 can be explicitly specified in this case.
-
-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, GNAT adds a rule
-to the static matching rules that requires object sizes to match.
-Consider this example:
-
-@example
- 1. procedure BadAVConvert is
- 2.    type R is new Integer;
- 3.    subtype R1 is R range 1 .. 10;
- 4.    subtype R2 is R range 1 .. 10;
- 5.    for R1'Object_Size use 8;
- 6.    for R2'Object_Size use 16;
- 7.    type R1P is access all R1;
- 8.    type R2P is access all R2;
- 9.    R1PV : R1P := new R1'(4);
-10.    R2PV : R2P;
-11. begin
-12.    R2PV := R2P (R1PV);
-               |
-       >>> target designated subtype not compatible with
-           type "R1" defined at line 3
-
-13. end;
-@end example
-
-In the absence of lines 5 and 6,
-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, 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{192}
-@section Attribute Old
-
-
-@geindex Old
-
-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 @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{193}
-@section Attribute Passed_By_Reference
-
-
-@geindex Parameters
-@geindex when passed by reference
-
-@geindex Passed_By_Reference
-
-@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{194}
-@section Attribute Pool_Address
-
-
-@geindex Pool_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{X'Pool_Address} returns the address of those bounds,
-whereas @code{X'Address} returns the address of the first
-component.
-
-Here, we are interpreting ‘storage pool’ broadly to mean
-@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 @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{195}
-@section Attribute Range_Length
-
-
-@geindex Range_Length
-
-@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.  @code{Range_Length}
-applied to the index subtype of a one dimensional array always gives the
-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{196}
-@section Attribute Restriction_Set
-
-
-@geindex Restriction_Set
-
-@geindex Restrictions
-
-This attribute allows compile time testing of restrictions that
-are currently in effect. It is primarily intended for specializing
-code in the run-time based on restrictions that are active (e.g.
-don’t need to save fpt registers if restriction No_Floating_Point
-is known to be in effect), but can be used anywhere.
-
-There are two forms:
-
-@example
-System'Restriction_Set (partition_boolean_restriction_NAME)
-System'Restriction_Set (No_Dependence => library_unit_NAME);
-@end example
-
-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 @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
-be in effect. An important guarantee is that the value of
-a Restriction_Set attribute is known to be consistent throughout
-all the code of a partition.
-
-This is trivially achieved if the entire partition is compiled
-with a consistent set of restriction pragmas. However, the
-compilation model does not require this. It is possible to
-compile one set of units with one set of pragmas, and another
-set of units with another set of pragmas. It is even possible
-to compile a spec with one set of pragmas, and then WITH the
-same spec with a different set of pragmas. Inconsistencies
-in the actual use of the restriction are checked at bind time.
-
-In order to achieve the guarantee of consistency for the
-Restriction_Set pragma, we consider that a use of the pragma
-that yields False is equivalent to a violation of the
-restriction.
-
-So for example if you write
-
-@example
-if System'Restriction_Set (No_Floating_Point) then
-   ...
-else
-   ...
-end if;
-@end example
-
-And the result is False, so that the else branch is executed,
-you can assume that this restriction is not set for any unit
-in the partition. This is checked by considering this use of
-the restriction pragma to be a violation of the restriction
-No_Floating_Point. This means that no other unit can attempt
-to set this restriction (if some unit does attempt to set it,
-the binder will refuse to bind the partition).
-
-Technical note: The restriction name and the unit name are
-intepreted entirely syntactically, as in the corresponding
-Restrictions pragma, they are not analyzed semantically,
-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{197}
-@section Attribute Result
-
-
-@geindex Result
-
-@code{function'Result} can only be used with in a Postcondition pragma
-for a function. The prefix must be the name of the corresponding function. This
-is used to refer to the result of the function in the postcondition expression.
-For a further discussion of the use of this attribute and examples of its use,
-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{198}
-@section Attribute Safe_Emax
-
-
-@geindex Ada 83 attributes
-
-@geindex Safe_Emax
-
-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{199}
-@section Attribute Safe_Large
-
-
-@geindex Ada 83 attributes
-
-@geindex Safe_Large
-
-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{19a}
-@section Attribute Safe_Small
-
-
-@geindex Ada 83 attributes
-
-@geindex Safe_Small
-
-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 attribute-scalar-storage-order}@anchor{14f}@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{19b}
-@section Attribute Scalar_Storage_Order
-
-
-@geindex Endianness
-
-@geindex Scalar storage order
-
-@geindex Scalar_Storage_Order
-
-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:
-
-@example
---  Component type definitions
-
-subtype Yr_Type is Natural range 0 .. 127;
-subtype Mo_Type is Natural range 1 .. 12;
-subtype Da_Type is Natural range 1 .. 31;
-
---  Record declaration
-
-type Date is record
-   Years_Since_1980 : Yr_Type;
-   Month            : Mo_Type;
-   Day_Of_Month     : Da_Type;
-end record;
-
---  Record representation clause
-
-for Date use record
-   Years_Since_1980 at 0 range 0  ..  6;
-   Month            at 0 range 7  .. 10;
-   Day_Of_Month     at 0 range 11 .. 15;
-end record;
-
---  Attribute definition clauses
-
-for Date'Bit_Order use System.High_Order_First;
-for Date'Scalar_Storage_Order use System.High_Order_First;
---  If Scalar_Storage_Order is specified, it must be consistent with
---  Bit_Order, so it's best to always define the latter explicitly if
---  the former is used.
-@end example
-
-Other properties are as for the standard representation attribute @code{Bit_Order}
-defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}.
-
-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 @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
-types. This may be overridden for the derived type by giving an explicit scalar
-storage order for it. However, for a record extension, the derived type must
-have the same scalar storage order as the parent 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 @code{Scalar_Storage_Order}
-attribute definition may be aliased.
-
-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 @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
-is done for writes.
-
-In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components
-are relaxed. Instead, the following rules apply:
-
-
-@itemize *
-
-@item 
-the underlying storage elements are those at positions
-@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
-a size no greater than the largest machine scalar
-
-@item 
-the enclosing machine scalar is defined as the smallest machine
-scalar starting at a position no greater than
-@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
-scalar.
-@end itemize
-
-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 @code{Default_Scalar_Storage_Order}.
-
-If a component of @code{T} is itself of a record or array type, the specfied
-@code{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.
-
-Representation changes that explicitly or implicitly toggle the scalar storage
-order are not supported and may result in erroneous execution of the program,
-except when performed by means of an instance of @code{Ada.Unchecked_Conversion}.
-
-In particular, overlays are not supported and a warning is given for them:
-
-@example
-type Rec_LE is record
-   I : Integer;
-end record;
-
-for Rec_LE use record
-   I at 0 range 0 .. 31;
-end record;
-
-for Rec_LE'Bit_Order use System.Low_Order_First;
-for Rec_LE'Scalar_Storage_Order use System.Low_Order_First;
-
-type Rec_BE is record
-   I : Integer;
-end record;
-
-for Rec_BE use record
-   I at 0 range 0 .. 31;
-end record;
-
-for Rec_BE'Bit_Order use System.High_Order_First;
-for Rec_BE'Scalar_Storage_Order use System.High_Order_First;
-
-R_LE : Rec_LE;
-
-R_BE : Rec_BE;
-for R_BE'Address use R_LE'Address;
-@end example
-
-@code{warning: overlay changes scalar storage order [enabled by default]}
-
-In most cases, such representation changes ought to be replaced by an
-instantiation of a function or procedure provided by @code{GNAT.Byte_Swapping}.
-
-Note that the scalar storage order only affects the in-memory data
-representation. It has no effect on the representation used by stream
-attributes.
-
-Note that debuggers may be unable to display the correct value of scalar
-components of a type for which the opposite storage order is specified.
-
-@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{e4}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{19c}
-@section Attribute Simple_Storage_Pool
-
-
-@geindex Storage pool
-@geindex simple
-
-@geindex Simple storage pool
-
-@geindex Simple_Storage_Pool
-
-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
-My_Pool : My_Simple_Storage_Pool_Type;
-
-type Acc is access My_Data_Type;
-
-for Acc'Simple_Storage_Pool use My_Pool;
-@end example
-
-The name given in an attribute_definition_clause for the
-@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
-for which it has been specified. The type of the attribute is the 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 @code{Storage_Pool} and @code{Simple_Storage_Pool}
-for the same access type.
-
-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 @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 @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
-`simple storage pool' substituted for `storage 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'.
-
-@node Attribute Small,Attribute Small_Denominator,Attribute Simple_Storage_Pool,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{19d}
-@section Attribute Small
-
-
-@geindex Ada 83 attributes
-
-@geindex Small
-
-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
-the Ada 83 reference manual for an exact description of the semantics of
-this attribute when applied to floating-point types.
-
-@node Attribute Small_Denominator,Attribute Small_Numerator,Attribute Small,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-small-denominator}@anchor{19e}
-@section Attribute Small_Denominator
-
-
-@geindex Small
-
-@geindex Small_Denominator
-
-@code{typ'Small_Denominator} for any fixed-point subtype @cite{typ} yields the
-denominator in the representation of @code{typ'Small} as a rational number
-with coprime factors (i.e. as an irreducible fraction).
-
-@node Attribute Small_Numerator,Attribute Storage_Unit,Attribute Small_Denominator,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-small-numerator}@anchor{19f}
-@section Attribute Small_Numerator
-
-
-@geindex Small
-
-@geindex Small_Numerator
-
-@code{typ'Small_Numerator} for any fixed-point subtype @cite{typ} yields the
-numerator in the representation of @code{typ'Small} as a rational number
-with coprime factors (i.e. as an irreducible fraction).
-
-@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small_Numerator,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a0}
-@section Attribute Storage_Unit
-
-
-@geindex Storage_Unit
-
-@code{Standard'Storage_Unit} (@code{Standard} is the only allowed
-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{1a1}
-@section Attribute Stub_Type
-
-
-@geindex Stub_Type
-
-The GNAT implementation of remote access-to-classwide types is
-organized as described in AARM section E.4 (20.t): a value of an RACW type
-(designating a remote object) is represented as a normal access
-value, pointing to a “stub” object which in turn contains the
-necessary information to contact the designated remote object. A
-call on any dispatching operation of such a stub object does the
-remote call, if necessary, using the information in the stub object
-to locate the target partition, etc.
-
-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 @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{1a2}
-@section Attribute System_Allocator_Alignment
-
-
-@geindex Alignment
-@geindex allocator
-
-@geindex System_Allocator_Alignment
-
-@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only
-allowed prefix) provides the observable guaranteed 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
-with alignment too large or to enable a realignment circuitry if the
-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{1a3}
-@section Attribute Target_Name
-
-
-@geindex Target_Name
-
-@code{Standard'Target_Name} (@code{Standard} is the only allowed
-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{1a4}
-@section Attribute To_Address
-
-
-@geindex To_Address
-
-The @code{System'To_Address}
-(@code{System} is the only allowed prefix)
-denotes a function identical to
-@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
-used in contexts (e.g., preelaborable packages) which require a
-static expression and where the function call could not be used
-(since the function call is always nonstatic, even if its
-argument is static). The argument must be in the range
--(2**(m-1)) .. 2**m-1, where m is the memory size
-(typically 32 or 64). Negative values are intepreted in a
-modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on
-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{1a5}
-@section Attribute To_Any
-
-
-@geindex To_Any
-
-This internal attribute is used for the generation of remote subprogram
-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{1a6}
-@section Attribute Type_Class
-
-
-@geindex Type_Class
-
-@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:
-
-@example
-type Type_Class is
-  (Type_Class_Enumeration,
-   Type_Class_Integer,
-   Type_Class_Fixed_Point,
-   Type_Class_Floating_Point,
-   Type_Class_Array,
-   Type_Class_Record,
-   Type_Class_Access,
-   Type_Class_Task,
-   Type_Class_Address);
-@end example
-
-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{1a7}
-@section Attribute Type_Key
-
-
-@geindex Type_Key
-
-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{1a8}
-@section Attribute TypeCode
-
-
-@geindex TypeCode
-
-This internal attribute is used for the generation of remote subprogram
-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{1a9}
-@section Attribute Unconstrained_Array
-
-
-@geindex Unconstrained_Array
-
-The @code{Unconstrained_Array} attribute can be used with a prefix that
-denotes any type or subtype. It is a static attribute that yields
-@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{1aa}
-@section Attribute Universal_Literal_String
-
-
-@geindex Named numbers
-@geindex representation of
-
-@geindex Universal_Literal_String
-
-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
-conversions and without the need to enclose the strings in quotes (which
-would preclude their use as numbers).
-
-For example, the following program prints the first 50 digits of pi:
-
-@example
-with Text_IO; use Text_IO;
-with Ada.Numerics;
-procedure Pi is
-begin
-   Put (Ada.Numerics.Pi'Universal_Literal_String);
-end;
-@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{1ab}
-@section Attribute Unrestricted_Access
-
-
-@geindex Access
-@geindex unrestricted
-
-@geindex Unrestricted_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 @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
-@code{Address} attribute and then doing an unchecked conversion to a
-desired access type.
-
-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
-has returned, such calls are erroneous. For example:
-
-@example
-package body P is
-
-   type Less_Nested is not null access procedure;
-   Global : Less_Nested;
-
-   procedure P1 is
-   begin
-      Global.all;
-   end P1;
-
-   procedure P2 is
-      Local_Var : Integer;
-
-      procedure More_Nested is
-      begin
-         ... Local_Var ...
-      end More_Nested;
-   begin
-      Global := More_Nested'Unrestricted_Access;
-      P1;
-   end P2;
-
-end P;
-@end example
-
-When P1 is called from P2, the call via Global is OK, but if P1 were
-called after P2 returns, it would be an erroneous use of a dangling
-pointer.
-
-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 @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
-if the pointer has the normal default ‘fat’ representation where a
-pointer has two components, one points to the array and one points to
-the bounds. If a size clause is used to force ‘thin’ representation
-for a pointer to unconstrained where there is only space for a single
-pointer, then the resulting pointer is not usable.
-
-In the simple case where a direct use of Unrestricted_Access attempts
-to make a thin pointer for a non-aliased object, the compiler will
-reject the use as illegal, as shown in the following example:
-
-@example
-with System; use System;
-procedure SliceUA2 is
-   type A is access all String;
-   for A'Size use Standard'Address_Size;
-
-   procedure P (Arg : A) is
-   begin
-      null;
-   end P;
-
-   X : String := "hello world!";
-   X2 : aliased String := "hello world!";
-
-   AV : A := X'Unrestricted_Access;    -- ERROR
-             |
->>> illegal use of Unrestricted_Access attribute
->>> attempt to generate thin pointer to unaliased object
-
-begin
-   P (X'Unrestricted_Access);          -- ERROR
-      |
->>> illegal use of Unrestricted_Access attribute
->>> attempt to generate thin pointer to unaliased object
-
-   P (X(7 .. 12)'Unrestricted_Access); -- ERROR
-      |
->>> illegal use of Unrestricted_Access attribute
->>> attempt to generate thin pointer to unaliased object
-
-   P (X2'Unrestricted_Access);         -- OK
-end;
-@end example
-
-but other cases cannot be detected by the compiler, and are
-considered to be erroneous. Consider the following example:
-
-@example
-with System; use System;
-with System; use System;
-procedure SliceUA is
-   type AF is access all String;
-
-   type A is access all String;
-   for A'Size use Standard'Address_Size;
-
-   procedure P (Arg : A) is
-   begin
-      if Arg'Length /= 6 then
-         raise Program_Error;
-      end if;
-   end P;
-
-   X : String := "hello world!";
-   Y : AF := X (7 .. 12)'Unrestricted_Access;
-
-begin
-   P (A (Y));
-end;
-@end example
-
-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 @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 @code{Program_Error} exception.
-
-In general, it is advisable to completely
-avoid mixing the use of thin pointers and the use of
-@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.
-
-Another erroneous situation arises if the attribute is
-applied to a constant. The resulting pointer can be used to access the
-constant, but the effect of trying to modify a constant in this manner
-is not well-defined. Consider this example:
-
-@example
-P : constant Integer := 4;
-type R is access all Integer;
-RV : R := P'Unrestricted_Access;
-..
-RV.all := 3;
-@end example
-
-Here we attempt to modify the constant P from 4 to 3, but the compiler may
-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
-@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
-   type R is access all Character;
-   RV : R := S (3)'Unrestricted_Access;
-begin
-   RV.all := 'a';
-end;
-@end example
-
-In general this is a risky approach. It may appear to “work” but such uses of
-@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_Value,Attribute Unrestricted_Access,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1ac}
-@section Attribute Update
-
-
-@geindex Update
-
-The @code{Update} attribute creates a copy of an array or record value
-with one or more modified components. The syntax is:
-
-@example
-PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST )
-PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} )
-PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION
-                @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} )
-
-MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION
-INDEX_EXPRESSION_LIST_LIST                   ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @}
-INDEX_EXPRESSION_LIST                        ::= ( EXPRESSION @{, EXPRESSION @} )
-@end example
-
-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
-original value of the array or record value is not affected. For
-example:
-
-@example
-type Arr is Array (1 .. 5) of Integer;
-...
-Avar1 : Arr := (1,2,3,4,5);
-Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20);
-@end example
-
-yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1}
-begin unmodified. Similarly:
-
-@example
-type Rec is A, B, C : Integer;
-...
-Rvar1 : Rec := (A => 1, B => 2, C => 3);
-Rvar2 : Rec := Rvar1'Update (B => 20);
-@end example
-
-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:
-
-@example
-Avar1 := Avar1'Update (1 => 10, 2 => Function_Call);
-@end example
-
-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 @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 @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.
-
-In the record case, no component can be mentioned more than once. In
-the array case, two overlapping ranges can appear in the association list,
-in which case the modifications are processed left to right.
-
-Multi-dimensional arrays can be modified, as shown by this example:
-
-@example
-A : array (1 .. 10, 1 .. 10) of Integer;
-..
-A := A'Update ((1, 2) => 20, (3, 4) => 30);
-@end example
-
-which changes element (1,2) to 20 and (3,4) to 30.
-
-@node Attribute Valid_Value,Attribute Valid_Scalars,Attribute Update,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-valid-value}@anchor{1ad}
-@section Attribute Valid_Value
-
-
-@geindex Valid_Value
-
-The @code{'Valid_Value} attribute is defined for enumeration types other than
-those in package Standard. This attribute is a function that takes
-a String, and returns Boolean. @code{T'Valid_Value (S)} returns True
-if and only if @code{T'Value (S)} would not raise Constraint_Error.
-
-@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Valid_Value,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1ae}
-@section Attribute Valid_Scalars
-
-
-@geindex Valid_Scalars
-
-The @code{'Valid_Scalars} attribute is intended to make it easier to check the
-validity of scalar subcomponents of composite objects. The attribute is defined
-for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type
-except for tagged private or @code{Unchecked_Union} types. The value of the
-attribute is of type @code{Boolean}.
-
-@code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of
-@code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if
-@code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent
-to attribute @code{'Valid} for scalar types.
-
-It is not specified in what order the subcomponents are checked, nor whether
-any more are checked after any one of them is determined to be invalid. If the
-prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated
-specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then
-only the subcomponents of @code{T} are checked; in other words, components of
-extensions of @code{T} are not checked even if @code{T'Class (P)'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 subcomponents.
-
-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{1af}
-@section Attribute VADS_Size
-
-
-@geindex Size
-@geindex VADS compatibility
-
-@geindex VADS_Size
-
-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, @code{'VADS_Size} applied
-to a predefined or other primitive type with no Size clause yields the
-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 attribute-value-size}@anchor{15d}@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b0}
-@section Attribute Value_Size
-
-
-@geindex Size
-@geindex setting for not-first subtype
-
-@geindex 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 @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{1b1}
-@section Attribute Wchar_T_Size
-
-
-@geindex Wchar_T_Size
-
-@code{Standard'Wchar_T_Size} (@code{Standard} is the only allowed
-prefix) provides the size in bits of the C @code{wchar_t} type
-primarily for constructing the definition of this type in
-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{1b2}
-@section Attribute Word_Size
-
-
-@geindex Word_Size
-
-@code{Standard'Word_Size} (@code{Standard} is the only allowed
-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 doc}@anchor{1b3}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1b4}@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9}
-@chapter Standard and Implementation Defined Restrictions
-
-
-All Ada Reference Manual-defined Restriction identifiers are implemented:
-
-
-@itemize *
-
-@item 
-language-defined restrictions (see 13.12.1)
-
-@item 
-tasking restrictions (see D.7)
-
-@item 
-high integrity restrictions (see H.4)
-@end itemize
-
-GNAT implements additional restriction identifiers. All restrictions, whether
-language defined or GNAT-specific, are listed in the following.
-
-@menu
-* Partition-Wide Restrictions:: 
-* Program Unit Level Restrictions:: 
-
-@end menu
-
-@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b5}@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1b6}
-@section Partition-Wide Restrictions
-
-
-There are two separate lists of restriction identifiers. The first
-set requires consistency throughout a partition (in other words, if the
-restriction identifier is used for any compilation unit in the partition,
-then all compilation units in the partition must obey the restriction).
-
-@menu
-* Immediate_Reclamation:: 
-* Max_Asynchronous_Select_Nesting:: 
-* Max_Entry_Queue_Length:: 
-* Max_Protected_Entries:: 
-* Max_Select_Alternatives:: 
-* Max_Storage_At_Blocking:: 
-* Max_Task_Entries:: 
-* Max_Tasks:: 
-* No_Abort_Statements:: 
-* No_Access_Parameter_Allocators:: 
-* No_Access_Subprograms:: 
-* No_Allocators:: 
-* No_Anonymous_Allocators:: 
-* No_Asynchronous_Control:: 
-* No_Calendar:: 
-* No_Coextensions:: 
-* No_Default_Initialization:: 
-* No_Delay:: 
-* No_Dependence:: 
-* No_Direct_Boolean_Operators:: 
-* No_Dispatch:: 
-* No_Dispatching_Calls:: 
-* No_Dynamic_Attachment:: 
-* No_Dynamic_Priorities:: 
-* No_Entry_Calls_In_Elaboration_Code:: 
-* No_Enumeration_Maps:: 
-* No_Exception_Handlers:: 
-* No_Exception_Propagation:: 
-* No_Exception_Registration:: 
-* No_Exceptions:: 
-* No_Finalization:: 
-* No_Fixed_Point:: 
-* No_Floating_Point:: 
-* No_Implicit_Conditionals:: 
-* No_Implicit_Dynamic_Code:: 
-* No_Implicit_Heap_Allocations:: 
-* No_Implicit_Protected_Object_Allocations:: 
-* No_Implicit_Task_Allocations:: 
-* No_Initialize_Scalars:: 
-* No_IO:: 
-* No_Local_Allocators:: 
-* No_Local_Protected_Objects:: 
-* No_Local_Tagged_Types:: 
-* No_Local_Timing_Events:: 
-* No_Long_Long_Integers:: 
-* No_Multiple_Elaboration:: 
-* No_Nested_Finalization:: 
-* No_Protected_Type_Allocators:: 
-* No_Protected_Types:: 
-* No_Recursion:: 
-* No_Reentrancy:: 
-* No_Relative_Delay:: 
-* No_Requeue_Statements:: 
-* No_Secondary_Stack:: 
-* No_Select_Statements:: 
-* No_Specific_Termination_Handlers:: 
-* No_Specification_of_Aspect:: 
-* No_Standard_Allocators_After_Elaboration:: 
-* No_Standard_Storage_Pools:: 
-* No_Stream_Optimizations:: 
-* No_Streams:: 
-* No_Tagged_Type_Registration:: 
-* No_Task_Allocators:: 
-* No_Task_At_Interrupt_Priority:: 
-* No_Task_Attributes_Package:: 
-* No_Task_Hierarchy:: 
-* No_Task_Termination:: 
-* No_Tasking:: 
-* No_Terminate_Alternatives:: 
-* No_Unchecked_Access:: 
-* No_Unchecked_Conversion:: 
-* No_Unchecked_Deallocation:: 
-* No_Use_Of_Entity:: 
-* Pure_Barriers:: 
-* Simple_Barriers:: 
-* Static_Priorities:: 
-* Static_Storage_Size:: 
-
-@end menu
-
-@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b7}
-@subsection Immediate_Reclamation
-
-
-@geindex Immediate_Reclamation
-
-[RM H.4] This restriction ensures that, except for storage occupied by
-objects created by allocators and not deallocated via unchecked
-deallocation, any storage reserved at run time for an object is
-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{1b8}
-@subsection Max_Asynchronous_Select_Nesting
-
-
-@geindex Max_Asynchronous_Select_Nesting
-
-[RM D.7] Specifies the maximum dynamic nesting level of asynchronous
-selects. Violations of this restriction with a value of zero are
-detected at compile time. Violations of this restriction with values
-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{1b9}
-@subsection Max_Entry_Queue_Length
-
-
-@geindex Max_Entry_Queue_Length
-
-[RM D.7] This restriction is a declaration that any protected entry compiled in
-the scope of the restriction has at most the specified number of
-tasks waiting on the entry at any one time, and so no queue is required.
-Note that this restriction is checked at run time. Violation of this
-restriction results in the raising of Program_Error exception at the point of
-the call.
-
-@geindex Max_Entry_Queue_Depth
-
-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{1ba}
-@subsection Max_Protected_Entries
-
-
-@geindex Max_Protected_Entries
-
-[RM D.7] Specifies the maximum number of entries per protected type. The
-bounds of every entry family of a protected unit shall be static, or shall be
-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{1bb}
-@subsection Max_Select_Alternatives
-
-
-@geindex 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{1bc}
-@subsection Max_Storage_At_Blocking
-
-
-@geindex Max_Storage_At_Blocking
-
-[RM D.7] Specifies the maximum portion (in storage elements) of a task’s
-Storage_Size that can be retained by a blocked task. A violation of this
-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{1bd}
-@subsection Max_Task_Entries
-
-
-@geindex Max_Task_Entries
-
-[RM D.7] Specifies the maximum number of entries
-per task.  The bounds of every entry family
-of a task unit shall be static, or shall be
-defined by a discriminant of a subtype whose
-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{1be}
-@subsection Max_Tasks
-
-
-@geindex Max_Tasks
-
-[RM D.7] Specifies the maximum number of task that may be created, not
-counting the creation of the environment task.  Violations of this
-restriction with a value of zero are detected at compile
-time. Violations of this restriction with values other than zero cause
-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{1bf}
-@subsection No_Abort_Statements
-
-
-@geindex No_Abort_Statements
-
-[RM D.7] There are no abort_statements, and there are
-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{1c0}
-@subsection No_Access_Parameter_Allocators
-
-
-@geindex No_Access_Parameter_Allocators
-
-[RM H.4] This restriction ensures at compile time that there are no
-occurrences of an allocator as the actual parameter to an access
-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{1c1}
-@subsection No_Access_Subprograms
-
-
-@geindex No_Access_Subprograms
-
-[RM H.4] This restriction ensures at compile time that there are no
-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{1c2}
-@subsection No_Allocators
-
-
-@geindex No_Allocators
-
-[RM H.4] This restriction ensures at compile time that there are no
-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{1c3}
-@subsection No_Anonymous_Allocators
-
-
-@geindex No_Anonymous_Allocators
-
-[RM H.4] This restriction ensures at compile time that there are no
-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{1c4}
-@subsection No_Asynchronous_Control
-
-
-@geindex No_Asynchronous_Control
-
-[RM J.13] This restriction ensures at compile time that there are no semantic
-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{1c5}
-@subsection No_Calendar
-
-
-@geindex No_Calendar
-
-[GNAT] This restriction ensures at compile time that there are no semantic
-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{1c6}
-@subsection No_Coextensions
-
-
-@geindex No_Coextensions
-
-[RM H.4] This restriction ensures at compile time that there are no
-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{1c7}
-@subsection No_Default_Initialization
-
-
-@geindex No_Default_Initialization
-
-[GNAT] This restriction prohibits any instance of default initialization
-of variables.  The binder implements a consistency rule which prevents
-any unit compiled without the restriction from with’ing a unit with the
-restriction (this allows the generation of initialization procedures to
-be skipped, since you can be sure that no call is ever generated to an
-initialization procedure in a unit with the restriction active). If used
-in conjunction with Initialize_Scalars or Normalize_Scalars, the effect
-is to prohibit all cases of variables declared without a specific
-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{1c8}
-@subsection No_Delay
-
-
-@geindex No_Delay
-
-[RM H.4] This restriction ensures at compile time that there are no
-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{1c9}
-@subsection No_Dependence
-
-
-@geindex No_Dependence
-
-[RM 13.12.1] This restriction ensures at compile time that there are no
-dependences on a library unit. For GNAT, this includes implicit implementation
-dependences on units of the runtime library that are created by the compiler
-to support specific constructs of the language.
-
-@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{1ca}
-@subsection No_Direct_Boolean_Operators
-
-
-@geindex No_Direct_Boolean_Operators
-
-[GNAT] This restriction ensures that no logical operators (and/or/xor)
-are used on operands of type Boolean (or any type derived from Boolean).
-This is intended for use in safety critical programs where the certification
-protocol requires the use of short-circuit (and then, or else) forms for all
-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{1cb}
-@subsection No_Dispatch
-
-
-@geindex No_Dispatch
-
-[RM H.4] This restriction ensures at compile time that there are no
-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{1cc}
-@subsection No_Dispatching_Calls
-
-
-@geindex No_Dispatching_Calls
-
-[GNAT] This restriction ensures at compile time that the code generated by the
-compiler involves no dispatching calls. The use of this restriction allows the
-safe use of record extensions, classwide membership tests and other classwide
-features not involving implicit dispatching. This restriction ensures that
-the code contains no indirect calls through a dispatching mechanism. Note that
-this includes internally-generated calls created by the compiler, for example
-in the implementation of class-wide objects assignments. The
-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
-@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.
-
-@example
-package Pkg is
-  type T is tagged record
-    Data : Natural;
-  end record;
-  procedure P (X : T);
-
-  type DT is new T with record
-    More_Data : Natural;
-  end record;
-  procedure Q (X : DT);
-end Pkg;
-
-with Pkg; use Pkg;
-procedure Example is
-  procedure Test (O : T'Class) is
-    N : Natural := O'Size; --  Error: Dispatching call
-    C : T'Class := O;      --  Error: implicit Dispatching Call
-  begin
-    if O in DT'Class then  --  OK   : Membership test
-       Q (DT (O));         --  OK   : Type conversion plus direct call
-    else
-       P (O);              --  Error: Dispatching call
-    end if;
-  end Test;
-
-  Obj : DT;
-begin
-  P (Obj);                 --  OK   : Direct call
-  P (T (Obj));             --  OK   : Type conversion plus direct call
-  P (T'Class (Obj));       --  Error: Dispatching call
-
-  Test (Obj);              --  OK   : Type conversion
-
-  if Obj in T'Class then   --  OK   : Membership test
-     null;
-  end if;
-end Example;
-@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{1cd}
-@subsection No_Dynamic_Attachment
-
-
-@geindex No_Dynamic_Attachment
-
-[RM D.7] This restriction ensures that there is no call to any of the
-operations defined in package Ada.Interrupts
-(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler,
-Detach_Handler, and Reference).
-
-@geindex No_Dynamic_Interrupts
-
-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{1ce}
-@subsection No_Dynamic_Priorities
-
-
-@geindex 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{1cf}
-@subsection No_Entry_Calls_In_Elaboration_Code
-
-
-@geindex No_Entry_Calls_In_Elaboration_Code
-
-[GNAT] This restriction ensures at compile time that no task or protected entry
-calls are made during elaboration code.  As a result of the use of this
-restriction, the compiler can assume that no code past an accept statement
-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{1d0}
-@subsection No_Enumeration_Maps
-
-
-@geindex No_Enumeration_Maps
-
-[GNAT] This restriction ensures at compile time that no operations requiring
-enumeration maps are used (that is Image and Value attributes applied
-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{1d1}
-@subsection No_Exception_Handlers
-
-
-@geindex No_Exception_Handlers
-
-[GNAT] This restriction ensures at compile time that there are no explicit
-exception handlers. It also indicates that no exception propagation will
-be provided. In this mode, exceptions may be raised but will result in
-an immediate call to the last chance handler, a routine that the user
-must define with the following profile:
-
-@example
-procedure Last_Chance_Handler
-  (Source_Location : System.Address; Line : Integer);
-pragma Export (C, Last_Chance_Handler,
-               "__gnat_last_chance_handler");
-@end example
-
-The parameter is a C null-terminated string representing a message to be
-associated with the exception (typically the source location of the raise
-statement generated by the compiler). The Line parameter when nonzero
-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{1d2}
-@subsection No_Exception_Propagation
-
-
-@geindex No_Exception_Propagation
-
-[GNAT] This restriction guarantees that exceptions are never propagated
-to an outer subprogram scope. The only case in which an exception may
-be raised is when the handler is statically in the same subprogram, so
-that the effect of a raise is essentially like a goto statement. Any
-other raise statement (implicit or explicit) will be considered
-unhandled. Exception handlers are allowed, but may not contain an
-exception occurrence identifier (exception choice). In addition, use of
-the package GNAT.Current_Exception is not permitted, and reraise
-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{1d3}
-@subsection No_Exception_Registration
-
-
-@geindex No_Exception_Registration
-
-[GNAT] This restriction ensures at compile time that no stream operations for
-types Exception_Id or Exception_Occurrence are used. This also makes it
-impossible to pass exceptions to or from a partition with this restriction
-in a distributed environment. If this restriction is active, the generated
-code is simplified by omitting the otherwise-required global 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{1d4}
-@subsection No_Exceptions
-
-
-@geindex No_Exceptions
-
-[RM H.4] This restriction ensures at compile time that there are no
-raise statements and no exception handlers and also suppresses the
-generation of language-defined run-time checks.
-
-@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d5}
-@subsection No_Finalization
-
-
-@geindex No_Finalization
-
-[GNAT] This restriction disables the language features described in
-chapter 7.6 of the Ada 2005 RM as well as all form of code generation
-performed by the compiler to support these features. The following types
-are no longer considered controlled when this restriction is in effect:
-
-
-@itemize *
-
-@item 
-@code{Ada.Finalization.Controlled}
-
-@item 
-@code{Ada.Finalization.Limited_Controlled}
-
-@item 
-Derivations from @code{Controlled} or @code{Limited_Controlled}
-
-@item 
-Class-wide types
-
-@item 
-Protected types
-
-@item 
-Task types
-
-@item 
-Array and record types with controlled components
-@end itemize
-
-The compiler no longer generates code to initialize, finalize or adjust an
-object or a nested component, either declared on the stack or on the heap. The
-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{1d6}
-@subsection No_Fixed_Point
-
-
-@geindex No_Fixed_Point
-
-[RM H.4] This restriction ensures at compile time that there are no
-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{1d7}
-@subsection No_Floating_Point
-
-
-@geindex No_Floating_Point
-
-[RM H.4] This restriction ensures at compile time that there are no
-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{1d8}
-@subsection No_Implicit_Conditionals
-
-
-@geindex No_Implicit_Conditionals
-
-[GNAT] This restriction ensures that the generated code does not contain any
-implicit conditionals, either by modifying the generated code where possible,
-or by rejecting any construct that would otherwise generate an implicit
-conditional. Note that this check does not include run time constraint
-checks, which on some targets may generate implicit conditionals as
-well. To control the latter, constraint checks can be suppressed in the
-normal manner. Constructs generating implicit conditionals include comparisons
-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{1d9}
-@subsection No_Implicit_Dynamic_Code
-
-
-@geindex No_Implicit_Dynamic_Code
-
-@geindex trampoline
-
-[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: @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
-protection) will cause trampolines to raise an exception.
-Trampolines are also quite slow at run time.
-
-On many targets, trampolines have been largely eliminated. Look at the
-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: @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{1da}
-@subsection No_Implicit_Heap_Allocations
-
-
-@geindex 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{1db}
-@subsection No_Implicit_Protected_Object_Allocations
-
-
-@geindex No_Implicit_Protected_Object_Allocations
-
-[GNAT] No constructs are allowed to cause implicit heap allocation of a
-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{1dc}
-@subsection No_Implicit_Task_Allocations
-
-
-@geindex 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{1dd}
-@subsection No_Initialize_Scalars
-
-
-@geindex No_Initialize_Scalars
-
-[GNAT] This restriction ensures that no unit in the partition is compiled with
-pragma Initialize_Scalars. This allows the generation of more efficient
-code, and in particular eliminates dummy null initialization routines that
-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{1de}
-@subsection No_IO
-
-
-@geindex No_IO
-
-[RM H.4] This restriction ensures at compile time that there are no
-dependences on any of the library units Sequential_IO, Direct_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{1df}
-@subsection No_Local_Allocators
-
-
-@geindex No_Local_Allocators
-
-[RM H.4] This restriction ensures at compile time that there are no
-occurrences of an allocator in subprograms, generic subprograms, tasks,
-and entry bodies.
-
-@node No_Local_Protected_Objects,No_Local_Tagged_Types,No_Local_Allocators,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e0}
-@subsection No_Local_Protected_Objects
-
-
-@geindex No_Local_Protected_Objects
-
-[RM D.7] This restriction ensures at compile time that protected objects are
-only declared at the library level.
-
-@node No_Local_Tagged_Types,No_Local_Timing_Events,No_Local_Protected_Objects,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-tagged-types}@anchor{1e1}
-@subsection No_Local_Tagged_Types
-
-
-@geindex No_Local_Tagged_Types
-
-[GNAT] This restriction ensures at compile time that tagged types are only
-declared at the library level.
-
-@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Tagged_Types,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e2}
-@subsection No_Local_Timing_Events
-
-
-@geindex No_Local_Timing_Events
-
-[RM D.7] All objects of type Ada.Real_Time.Timing_Events.Timing_Event are
-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{1e3}
-@subsection No_Long_Long_Integers
-
-
-@geindex No_Long_Long_Integers
-
-[GNAT] This partition-wide restriction forbids any explicit reference to
-type Standard.Long_Long_Integer, and also forbids declaring range types whose
-implicit base type is Long_Long_Integer, and modular types whose size exceeds
-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{1e4}
-@subsection No_Multiple_Elaboration
-
-
-@geindex No_Multiple_Elaboration
-
-[GNAT] When this restriction is active and the static elaboration model is
-used, and -fpreserve-control-flow is not used, the compiler is allowed to
-suppress the elaboration counter normally associated with the unit, even if
-the unit has elaboration code. This counter is typically used to check for
-access before elaboration and to control multiple elaboration attempts. If the
-restriction is used, then the situations in which multiple elaboration is
-possible, including non-Ada main programs and Stand Alone libraries, are not
-permitted and will be diagnosed 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{1e5}
-@subsection No_Nested_Finalization
-
-
-@geindex 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{1e6}
-@subsection No_Protected_Type_Allocators
-
-
-@geindex No_Protected_Type_Allocators
-
-[RM D.7] This restriction ensures at compile time that there are no allocator
-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{1e7}
-@subsection No_Protected_Types
-
-
-@geindex No_Protected_Types
-
-[RM H.4] This restriction ensures at compile time that there are no
-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{1e8}
-@subsection No_Recursion
-
-
-@geindex No_Recursion
-
-[RM H.4] A program execution is erroneous if a subprogram is invoked as
-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{1e9}
-@subsection No_Reentrancy
-
-
-@geindex No_Reentrancy
-
-[RM H.4] A program execution is erroneous if a subprogram is executed by
-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{1ea}
-@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 @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{1eb}
-@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 @code{requeue} from being used in source
-code.
-
-@geindex No_Requeue
-
-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{1ec}
-@subsection No_Secondary_Stack
-
-
-@geindex No_Secondary_Stack
-
-[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
-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{1ed}
-@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 @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{1ee}
-@subsection No_Specific_Termination_Handlers
-
-
-@geindex No_Specific_Termination_Handlers
-
-[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler
-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{1ef}
-@subsection No_Specification_of_Aspect
-
-
-@geindex No_Specification_of_Aspect
-
-[RM 13.12.1] This restriction checks at compile time that no aspect
-specification, attribute definition clause, or pragma is given for a
-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{1f0}
-@subsection No_Standard_Allocators_After_Elaboration
-
-
-@geindex No_Standard_Allocators_After_Elaboration
-
-[RM D.7] Specifies that an allocator using a standard storage pool
-should never be evaluated at run time after the elaboration of the
-library items of the partition has completed. Otherwise, Storage_Error
-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{1f1}
-@subsection No_Standard_Storage_Pools
-
-
-@geindex No_Standard_Storage_Pools
-
-[GNAT] This restriction ensures at compile time that no access types
-use the standard default storage pool.  Any access type declared must
-have an explicit Storage_Pool attribute defined specifying a
-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{1f2}
-@subsection No_Stream_Optimizations
-
-
-@geindex No_Stream_Optimizations
-
-[GNAT] This restriction affects the performance of stream operations on types
-@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 superior performance. When this restriction is in effect, the
-compiler performs all IO operations on a per-character basis.
-
-@node No_Streams,No_Tagged_Type_Registration,No_Stream_Optimizations,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1f3}
-@subsection No_Streams
-
-
-@geindex 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
-@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.
-
-Note that the use of restriction allows optimization of tagged types,
-since they do not need to worry about dispatching stream operations.
-To take maximum advantage of this space-saving optimization, any
-unit declaring a tagged type should be compiled with the restriction,
-though this is not required.
-
-@node No_Tagged_Type_Registration,No_Task_Allocators,No_Streams,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tagged-type-registration}@anchor{1f4}
-@subsection No_Tagged_Type_Registration
-
-
-@geindex No_Tagged_Type_Registration
-
-[GNAT] If this restriction is active, then class-wide streaming
-attributes are not supported. In addition, the subprograms in
-Ada.Tags are not supported.
-If this restriction is active, the generated code is simplified by
-omitting the otherwise-required global registration of tagged types when they
-are declared. This restriction may be necessary in order to also apply
-the No_Elaboration_Code restriction.
-
-@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Tagged_Type_Registration,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f5}
-@subsection No_Task_Allocators
-
-
-@geindex No_Task_Allocators
-
-[RM D.7] There are no allocators for task types
-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{1f6}
-@subsection No_Task_At_Interrupt_Priority
-
-
-@geindex No_Task_At_Interrupt_Priority
-
-[GNAT] This restriction ensures at compile time that there is no
-Interrupt_Priority aspect or pragma for a task or a task type. As
-a consequence, the tasks are always created with a priority below
-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{1f7}
-@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 @code{Ada.Task_Attributes}.
-
-@geindex No_Task_Attributes
-
-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{1f8}
-@subsection No_Task_Hierarchy
-
-
-@geindex No_Task_Hierarchy
-
-[RM D.7] All (non-environment) tasks depend
-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{1f9}
-@subsection No_Task_Termination
-
-
-@geindex 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{1fa}
-@subsection No_Tasking
-
-
-@geindex 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
-@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{1fb}
-@subsection No_Terminate_Alternatives
-
-
-@geindex 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{1fc}
-@subsection No_Unchecked_Access
-
-
-@geindex No_Unchecked_Access
-
-[RM H.4] This restriction ensures at compile time that there are no
-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{1fd}
-@subsection No_Unchecked_Conversion
-
-
-@geindex No_Unchecked_Conversion
-
-[RM J.13] This restriction ensures at compile time that there are no semantic
-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{1fe}
-@subsection No_Unchecked_Deallocation
-
-
-@geindex No_Unchecked_Deallocation
-
-[RM J.13] This restriction ensures at compile time that there are no semantic
-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{1ff}
-@subsection No_Use_Of_Entity
-
-
-@geindex No_Use_Of_Entity
-
-[GNAT] This restriction ensures at compile time that there are no references
-to the entity given in the form
-
-@example
-No_Use_Of_Entity => Name
-@end example
-
-where @code{Name} is the fully qualified entity, for example
-
-@example
-No_Use_Of_Entity => Ada.Text_IO.Put_Line
-@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{200}
-@subsection Pure_Barriers
-
-
-@geindex Pure_Barriers
-
-[GNAT] This restriction ensures at compile time that protected entry
-barriers are restricted to:
-
-
-@itemize *
-
-@item 
-components of the protected object (excluding selection from dereferences),
-
-@item 
-constant declarations,
-
-@item 
-named numbers,
-
-@item 
-enumeration literals,
-
-@item 
-integer literals,
-
-@item 
-real literals,
-
-@item 
-character literals,
-
-@item 
-implicitly defined comparison operators,
-
-@item 
-uses of the Standard.”not” operator,
-
-@item 
-short-circuit operator,
-
-@item 
-the Count attribute
-@end itemize
-
-This restriction is a relaxation of the Simple_Barriers restriction,
-but still ensures absence of side effects, exceptions, and recursion
-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{201}
-@subsection Simple_Barriers
-
-
-@geindex Simple_Barriers
-
-[RM D.7] This restriction ensures at compile time that barriers in entry
-declarations for protected types are restricted to either static boolean
-expressions or references to simple boolean variables defined in the private
-part of the protected type.  No other form of entry barriers is permitted.
-
-@geindex Boolean_Entry_Barriers
-
-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{202}
-@subsection Static_Priorities
-
-
-@geindex Static_Priorities
-
-[GNAT] This restriction ensures at compile time that all priority expressions
-are static, and that there are no dependences on the package
-@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{203}
-@subsection Static_Storage_Size
-
-
-@geindex Static_Storage_Size
-
-[GNAT] This restriction ensures at compile time that any expression appearing
-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 id3}@anchor{204}@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{205}
-@section Program Unit Level Restrictions
-
-
-The second set of restriction identifiers
-does not require partition-wide consistency.
-The restriction may be enforced for a single
-compilation unit without any effect on any of the
-other compilation units in the partition.
-
-@menu
-* No_Elaboration_Code:: 
-* No_Dynamic_Accessibility_Checks:: 
-* No_Dynamic_Sized_Objects:: 
-* No_Entry_Queue:: 
-* No_Implementation_Aspect_Specifications:: 
-* No_Implementation_Attributes:: 
-* No_Implementation_Identifiers:: 
-* No_Implementation_Pragmas:: 
-* No_Implementation_Restrictions:: 
-* No_Implementation_Units:: 
-* No_Implicit_Aliasing:: 
-* No_Implicit_Loops:: 
-* No_Obsolescent_Features:: 
-* No_Wide_Characters:: 
-* Static_Dispatch_Tables:: 
-* SPARK_05:: 
-
-@end menu
-
-@node No_Elaboration_Code,No_Dynamic_Accessibility_Checks,,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{206}
-@subsection No_Elaboration_Code
-
-
-@geindex 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 @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 @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,
-and exception declarations (which generate calls to a run-time
-registry procedure).  This restriction is enforced on
-a unit by unit basis, it need not be obeyed consistently
-throughout a partition.
-
-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 @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
-the data for the others clause must be repeatedly generated.
-
-It is not possible to precisely document
-the constructs which are compatible with this restriction, since,
-unlike most other restrictions, this is not a restriction on the
-source code, but a restriction on the generated object code. For
-example, if the source contains a declaration:
-
-@example
-Val : constant Integer := X;
-@end example
-
-where X is not a static constant, it may be possible, depending
-on complex optimization circuitry, for the compiler to figure
-out the value of X at compile time, in which case this initialization
-can be done by the loader, and requires no initialization code. It
-is not possible to document the precise conditions under which the
-optimizer can figure this out.
-
-Note that this the implementation of this restriction requires full
-code generation. If it is used in conjunction with “semantics only”
-checking, then some cases of violations may be missed.
-
-When this restriction is active, we are not requesting control-flow
-preservation with -fpreserve-control-flow, and the static elaboration model is
-used, the compiler is allowed to suppress the elaboration counter normally
-associated with the unit. This counter is typically used to check for access
-before elaboration and to control multiple elaboration attempts.
-
-@node No_Dynamic_Accessibility_Checks,No_Dynamic_Sized_Objects,No_Elaboration_Code,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-accessibility-checks}@anchor{207}
-@subsection No_Dynamic_Accessibility_Checks
-
-
-@geindex No_Dynamic_Accessibility_Checks
-
-[GNAT] No dynamic accessibility checks are generated when this restriction is
-in effect. Instead, dangling references are prevented via more conservative
-compile-time checking. More specifically, existing compile-time checks are
-enforced but with more conservative assumptions about the accessibility levels
-of the relevant entities. These conservative assumptions eliminate the need for
-dynamic accessibility checks.
-
-These new rules for computing (at compile-time) the accessibility level of an
-anonymous access type T are as follows:
-
-
-@itemize *
-
-@item 
-If T is a function result type then, from the caller’s perspective, its level
-is that of the innermost master enclosing the function call. From the callee’s
-perspective, the level of parameters and local variables of the callee is
-statically deeper than the level of T.
-
-For any other accessibility level L such that the level of parameters and local
-variables of the callee is statically deeper than L, the level of T (from the
-callee’s perspective) is also statically deeper than L.
-
-@item 
-If T is the type of a formal parameter then, from the caller’s perspective,
-its level is at least as deep as that of the type of the corresponding actual
-parameter (whatever that actual parameter might be). From the callee’s
-perspective, the level of parameters and local variables of the callee is
-statically deeper than the level of T.
-
-@item 
-If T is the type of a discriminant then its level is that of the discriminated
-type.
-
-@item 
-If T is the type of a stand-alone object then its level is the level of the
-object.
-
-@item 
-In all other cases, the level of T is as defined by the existing rules of Ada.
-@end itemize
-
-@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Dynamic_Accessibility_Checks,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{208}
-@subsection No_Dynamic_Sized_Objects
-
-
-@geindex No_Dynamic_Sized_Objects
-
-[GNAT] This restriction disallows certain constructs that might lead to the
-creation of dynamic-sized composite objects (or array or discriminated type).
-An array subtype indication is illegal if the bounds are not static
-or references to discriminants of an enclosing type.
-A discriminated subtype indication is illegal if the type has
-discriminant-dependent array components or a variant part, and the
-discriminants are not static. In addition, array and record aggregates are
-illegal in corresponding cases. Note that this restriction does not forbid
-access discriminants. It is often a good idea to combine this restriction
-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{209}
-@subsection No_Entry_Queue
-
-
-@geindex No_Entry_Queue
-
-[GNAT] This restriction is a declaration that any protected entry compiled in
-the scope of the restriction has at most one task waiting on the entry
-at any one time, and so no queue is required.  This restriction is not
-checked at compile time.  A program execution is erroneous if an attempt
-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{20a}
-@subsection No_Implementation_Aspect_Specifications
-
-
-@geindex No_Implementation_Aspect_Specifications
-
-[RM 13.12.1] This restriction checks at compile time that no
-GNAT-defined aspects are present.  With this restriction, the only
-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{20b}
-@subsection No_Implementation_Attributes
-
-
-@geindex No_Implementation_Attributes
-
-[RM 13.12.1] This restriction checks at compile time that no
-GNAT-defined attributes are present.  With this restriction, the only
-attributes that can be used are those defined in the Ada Reference
-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{20c}
-@subsection No_Implementation_Identifiers
-
-
-@geindex No_Implementation_Identifiers
-
-[RM 13.12.1] This restriction checks at compile time that no
-implementation-defined identifiers (marked with pragma Implementation_Defined)
-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{20d}
-@subsection No_Implementation_Pragmas
-
-
-@geindex No_Implementation_Pragmas
-
-[RM 13.12.1] This restriction checks at compile time that no
-GNAT-defined pragmas are present.  With this restriction, the only
-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{20e}
-@subsection No_Implementation_Restrictions
-
-
-@geindex No_Implementation_Restrictions
-
-[GNAT] This restriction checks at compile time that no GNAT-defined restriction
-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{20f}
-@subsection No_Implementation_Units
-
-
-@geindex No_Implementation_Units
-
-[RM 13.12.1] This restriction checks at compile time that there is no
-mention in the context clause of any implementation-defined descendants
-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{210}
-@subsection No_Implicit_Aliasing
-
-
-@geindex No_Implicit_Aliasing
-
-[GNAT] This restriction, which is not required to be partition-wide consistent,
-requires an explicit aliased keyword for an object to which ‘Access,
-‘Unchecked_Access, or ‘Address is applied, and forbids entirely the use of
-the ‘Unrestricted_Access attribute for objects. Note: the reason that
-Unrestricted_Access is forbidden is that it would require the prefix
-to be aliased, and in such cases, it can always be replaced by
-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{211}
-@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 @code{for} loops, either by
-modifying the generated code where possible, or by rejecting any construct
-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
-arrays larger than about 5000 scalar components. Note that if this restriction
-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{212}
-@subsection No_Obsolescent_Features
-
-
-@geindex No_Obsolescent_Features
-
-[RM 13.12.1] This restriction checks at compile time that no obsolescent
-features are used, as defined in Annex J of the Ada Reference Manual.
-
-@node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{213}
-@subsection No_Wide_Characters
-
-
-@geindex No_Wide_Characters
-
-[GNAT] This restriction ensures at compile time that no uses of the types
-@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 @code{Character}).
-
-@node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{214}
-@subsection Static_Dispatch_Tables
-
-
-@geindex Static_Dispatch_Tables
-
-[GNAT] This restriction checks at compile time that all the artifacts
-associated with dispatch tables can be placed in read-only memory.
-
-@node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{215}
-@subsection SPARK_05
-
-
-@geindex SPARK_05
-
-[GNAT] This restriction no longer has any effect and is superseded by
-SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that
-a codebase respects SPARK 2014 restrictions, mark the code with pragma or
-aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as
-follows:
-
-@example
-gnatprove -P project.gpr --mode=stone
-@end example
-
-or equivalently:
-
-@example
-gnatprove -P project.gpr --mode=check_all
-@end example
-
-@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top
-@anchor{gnat_rm/implementation_advice doc}@anchor{216}@anchor{gnat_rm/implementation_advice id1}@anchor{217}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}
-@chapter Implementation Advice
-
-
-The main text of the Ada Reference Manual describes the required
-behavior of all Ada compilers, and the GNAT compiler conforms to
-these requirements.
-
-In addition, there are sections throughout the Ada Reference Manual headed
-by the phrase ‘Implementation advice’.  These sections are not normative,
-i.e., they do not specify requirements that all compilers must
-follow.  Rather they provide advice on generally desirable behavior.
-They are not requirements, because they describe behavior that cannot
-be provided on all systems, or may be undesirable on some systems.
-
-As far as practical, GNAT follows the implementation advice in
-the Ada Reference Manual.  Each such RM section corresponds to a section
-in this chapter whose title specifies the
-RM section number and paragraph number and the subject of
-the advice.  The contents of each section consists of the RM text within
-quotation marks,
-followed by the GNAT interpretation of the advice.  Most often, this simply says
-‘followed’, which means that GNAT follows the advice.  However, in a
-number of cases, GNAT deliberately deviates from this advice, in which
-case the text describes what GNAT does and why.
-
-@geindex Error detection
-
-@menu
-* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 
-* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 
-* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 
-* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 
-* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 
-* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 
-* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 
-* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 
-* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 
-* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 
-* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 
-* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. 
-* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 
-* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 
-* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 
-* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 
-* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 
-* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 
-* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 
-* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 
-* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 
-* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 
-* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 
-* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 
-* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 
-* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 
-* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 
-* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 
-* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 
-* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 
-* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 
-* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. 
-* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 
-* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 
-* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 
-* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 
-* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 
-* RM A.18; Containers: RM A 18 Containers. 
-* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 
-* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 
-* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 
-* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 
-* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 
-* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 
-* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 
-* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 
-* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 
-* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 
-* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 
-* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 
-* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 
-* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 
-* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 
-* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 
-* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 
-* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 
-* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 
-* RM F(7); COBOL Support: RM F 7 COBOL Support. 
-* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 
-* RM G; Numerics: RM G Numerics. 
-* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 
-* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 
-* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 
-* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 
-* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 
-
-@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{218}
-@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 @code{Program_Error} if
-feasible.”
-@end quotation
-
-Not relevant.  All specialized needs annex features are either supported,
-or diagnosed at compile time.
-
-@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{219}
-@section RM 1.1.3(31): Child Units
-
-
-@quotation
-
-“If an implementation wishes to provide implementation-defined
-extensions to the functionality of a language-defined library unit, it
-should normally do so by adding children to the library unit.”
-@end quotation
-
-Followed.
-
-@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{21a}
-@section RM 1.1.5(12): Bounded Errors
-
-
-@quotation
-
-“If an implementation detects a bounded error or erroneous
-execution, it should raise @code{Program_Error}.”
-@end quotation
-
-Followed in all cases in which the implementation detects a bounded
-error or erroneous execution.  Not all such situations are detected at
-runtime.
-
-@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{21b}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{21c}
-@section RM 2.8(16): Pragmas
-
-
-@quotation
-
-“Normally, implementation-defined pragmas should have no semantic effect
-for error-free programs; that is, if the implementation-defined pragmas
-are removed from a working program, the program should still be legal,
-and should still have the same semantics.”
-@end quotation
-
-The following implementation defined pragmas are exceptions to this
-rule:
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 
-@headitem
-
-Pragma
-
-@tab
-
-Explanation
-
-@item
-
-`Abort_Defer'
-
-@tab
-
-Affects semantics
-
-@item
-
-`Ada_83'
-
-@tab
-
-Affects legality
-
-@item
-
-`Assert'
-
-@tab
-
-Affects semantics
-
-@item
-
-`CPP_Class'
-
-@tab
-
-Affects semantics
-
-@item
-
-`CPP_Constructor'
-
-@tab
-
-Affects semantics
-
-@item
-
-`Debug'
-
-@tab
-
-Affects semantics
-
-@item
-
-`Interface_Name'
-
-@tab
-
-Affects semantics
-
-@item
-
-`Machine_Attribute'
-
-@tab
-
-Affects semantics
-
-@item
-
-`Unimplemented_Unit'
-
-@tab
-
-Affects legality
-
-@item
-
-`Unchecked_Union'
-
-@tab
-
-Affects semantics
-
-@end multitable
-
-
-In each of the above cases, it is essential to the purpose of the pragma
-that this advice not be followed.  For details see
-@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{21d}
-@section RM 2.8(17-19): Pragmas
-
-
-@quotation
-
-“Normally, an implementation should not define pragmas that can
-make an illegal program legal, except as follows:
-
-
-@itemize *
-
-@item 
-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 @code{library_items}.”
-@end itemize
-@end quotation
-
-See @ref{21c,,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{21e}
-@section RM 3.5.2(5): Alternative Character Sets
-
-
-@quotation
-
-“If an implementation supports a mode with alternative interpretations
-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
-@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
-@code{identifier_letter}.”
-@end quotation
-
-Not all wide character modes follow this advice, in particular the JIS
-and IEC modes reflect standard usage in Japan, and in these encoding,
-the upper half of the Latin-1 set is not part of the wide-character
-subset, since the most significant bit is used for wide character
-encoding.  However, this only applies to the external forms.  Internally
-there is no such restriction.
-
-@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{21f}
-@section RM 3.5.4(28): Integer Types
-
-
-@quotation
-
-“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
-@code{Standard}.  Instead, appropriate named integer subtypes should be
-provided in the library package @code{Interfaces} (see B.2).”
-@end quotation
-
-@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{220}
-@section RM 3.5.4(29): Integer Types
-
-
-@quotation
-
-“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 @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{221}
-@section RM 3.5.5(8): Enumeration Values
-
-
-@quotation
-
-“For the evaluation of a call on @code{S'Pos} for an enumeration
-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
-@code{Program_Error}.  This is particularly important for enumeration
-types with noncontiguous internal codes specified by an
-enumeration_representation_clause.”
-@end quotation
-
-Followed.
-
-@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{222}
-@section RM 3.5.7(17): Float Types
-
-
-@quotation
-
-“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 @code{Standard}.  Instead, appropriate named floating point subtypes
-should be provided in the library package @code{Interfaces} (see B.2).”
-@end quotation
-
-@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 @code{Long_Float}, but on some machines, it will
-correspond to the IEEE extended form.  The notable case is all 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 arrays
-
-@geindex Arrays
-@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{223}
-@section RM 3.6.2(11): Multidimensional Arrays
-
-
-@quotation
-
-“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 @code{Convention}
-(@code{Fortran}, …) applies to a multidimensional array type, then
-column-major order should be used instead (see B.5, `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{224}
-@section RM 9.6(30-31): Duration’Small
-
-
-@quotation
-
-“Whenever possible in an implementation, the value of @code{Duration'Small}
-should be no greater than 100 microseconds.”
-@end quotation
-
-Followed.  (@code{Duration'Small} = 10**(-9)).
-
-@quotation
-
-“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{225}
-@section RM 10.2.1(12): Consistent Representation
-
-
-@quotation
-
-“In an implementation, a type declared in a pre-elaborated package should
-have the same representation in every elaboration of a given version of
-the package, whether the elaborations occur in distinct executions of
-the same program, or in executions of distinct programs or partitions
-that include the given version.”
-@end quotation
-
-Followed, except in the case of tagged types.  Tagged types involve
-implicit pointers to a local copy of a dispatch table, and these pointers
-have representations which thus depend on a particular elaboration of the
-package.  It is not easy to see how it would be possible to follow this
-advice without severely impacting efficiency of execution.
-
-@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{226}
-@section RM 11.4.1(19): Exception Information
-
-
-@quotation
-
-“@code{Exception_Message} by default and @code{Exception_Information}
-should produce information useful for
-debugging.  @code{Exception_Message} should be short, about one
-line.  @code{Exception_Information} can be long.  @code{Exception_Message}
-should not include the
-@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
-@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 @code{Discard_Names}.
-
-@geindex Suppression of checks
-
-@geindex 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{227}
-@section RM 11.5(28): Suppression of Checks
-
-
-@quotation
-
-“The implementation should minimize the code executed for checks that
-have been suppressed.”
-@end quotation
-
-Followed.
-
-@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{228}
-@section RM 13.1 (21-24): Representation Clauses
-
-
-@quotation
-
-“The recommended level of support for all representation items is
-qualified as follows:
-
-An implementation need not support representation items containing
-nonstatic expressions, except that an implementation should support a
-representation item for a given entity if each nonstatic expression in
-the representation item is a name that statically denotes a constant
-declared before the entity.”
-@end quotation
-
-Followed.  In fact, GNAT goes beyond the recommended level of support
-by allowing nonstatic expressions in some representation clauses even
-without the need to declare constants initialized with the values of
-such expressions.
-For example:
-
-@example
-  X : Integer;
-  Y : Float;
-  for Y'Address use X'Address;>>
-
-
-"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
-all static constraints."
-@end example
-
-Followed.  Size Clauses are not permitted on nonstatic components, as
-described above.
-
-@quotation
-
-“An aliased component, or a component whose type is by-reference, should
-always be allocated at an addressable location.”
-@end quotation
-
-Followed.
-
-@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{229}
-@section RM 13.2(6-8): Packed Types
-
-
-@quotation
-
-“If a type is packed, then the implementation should try to minimize
-storage allocated to objects of the type, possibly at the expense of
-speed of accessing components, subject to reasonable complexity in
-addressing calculations.
-
-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 `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 @code{Size} is
-greater than the word size may be allocated an integral number of words.”
-@end quotation
-
-Followed.  Tight packing of arrays is supported for all component sizes
-up to 64-bits. If the array component size is 1 (that is to say, if
-the component is a boolean type or an enumeration type with two values)
-then values of the type are implicitly initialized to zero. This
-happens both for objects of the packed type, and for objects that have a
-subcomponent of the packed type.
-
-@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{22a}
-@section RM 13.3(14-19): Address Clauses
-
-
-@quotation
-
-“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
-
-Followed.
-
-@quotation
-
-“The recommended level of support for the @code{Address} attribute is:
-
-@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
-@code{Address} has been specified.”
-@end quotation
-
-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.
-
-@quotation
-
-“An implementation should support @code{Address} clauses for imported
-subprograms.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“Objects (including subcomponents) that are aliased or of a by-reference
-type should be allocated on storage element boundaries.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“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
-
-Followed.
-
-@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{22b}
-@section RM 13.3(29-35): Alignment Clauses
-
-
-@quotation
-
-“The recommended level of support for the @code{Alignment} attribute for
-subtypes is:
-
-An implementation should support specified Alignments that are factors
-and multiples of the number of storage elements per word, subject to the
-following:”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An implementation need not support specified Alignments for
-combinations of Sizes and Alignments that cannot be easily
-loaded and stored by available machine instructions.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An implementation need not support specified Alignments that are
-greater than the maximum @code{Alignment} the implementation ever returns by
-default.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“The recommended level of support for the @code{Alignment} attribute for
-objects is:
-
-Same as above, for subtypes, but in addition:”
-@end quotation
-
-Followed.
-
-@quotation
-
-“For stand-alone library-level objects of statically constrained
-subtypes, the implementation should support all alignments
-supported by the target linker.  For example, page alignment is likely to
-be supported for such objects, but not for subtypes.”
-@end quotation
-
-Followed.
-
-@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{22c}
-@section RM 13.3(42-43): Size Clauses
-
-
-@quotation
-
-“The recommended level of support for the @code{Size} attribute of
-objects is:
-
-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 @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{22d}
-@section RM 13.3(50-56): Size Clauses
-
-
-@quotation
-
-“If the @code{Size} of a subtype is specified, and allows for efficient
-independent addressability (see 9.10) on the target architecture, then
-the @code{Size} of the following objects of the subtype should equal the
-@code{Size} of the subtype:
-
-Aliased objects (including components).”
-@end quotation
-
-Followed.
-
-@quotation
-
-“@cite{Size} clause on a composite subtype should not affect the
-internal layout of components.”
-@end quotation
-
-Followed. But note that this can be overridden by use of the implementation
-pragma Implicit_Packing in the case of packed arrays.
-
-@quotation
-
-“The recommended level of support for the @code{Size} attribute of subtypes is:
-
-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 @code{Size} for it that reflects this representation.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“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
-
-Followed.
-
-@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{22e}
-@section RM 13.3(71-73): Component Size Clauses
-
-
-@quotation
-
-“The recommended level of support for the @code{Component_Size}
-attribute is:
-
-An implementation need not support specified @code{Component_Sizes} that are
-less than the @code{Size} of the component subtype.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An implementation should support specified Component_Sizes that
-are factors and multiples of the word size.  For such
-Component_Sizes, the array should contain no gaps between
-components.  For other Component_Sizes (if supported), the array
-should contain no gaps between components when packing is also
-specified; the implementation should forbid this combination in cases
-where it cannot support a no-gaps representation.”
-@end quotation
-
-Followed.
-
-@geindex Enumeration representation clauses
-
-@geindex Representation clauses
-@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{22f}
-@section RM 13.4(9-10): Enumeration Representation Clauses
-
-
-@quotation
-
-“The recommended level of support for enumeration representation clauses
-is:
-
-An implementation need not support enumeration representation clauses
-for boolean types, but should at minimum support the internal codes in
-the range @code{System.Min_Int .. System.Max_Int}.”
-@end quotation
-
-Followed.
-
-@geindex Record representation clauses
-
-@geindex Representation clauses
-@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{230}
-@section RM 13.5.1(17-22): Record Representation Clauses
-
-
-@quotation
-
-“The recommended level of support for
-`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,
-shift, mask, store sequence, given the available machine instructions
-and run-time model.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“A storage place should be supported if its size is equal to the
-@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 @code{Size} is less than the word
-size, any storage place that does not cross an aligned word boundary
-should be supported.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An implementation may reserve a storage place for the tag field of a
-tagged type, and disallow other components from overlapping that place.”
-@end quotation
-
-Followed.  The storage place for the tag field is the beginning of the tagged
-record, and its size is Address’Size.  GNAT will reject an explicit component
-clause for the tag field.
-
-@quotation
-
-“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.”
-@end quotation
-
-Followed.  The above advice on record representation clauses is followed,
-and all mentioned features are implemented.
-
-@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{231}
-@section RM 13.5.2(5): Storage Place Attributes
-
-
-@quotation
-
-“If a component is represented using some form of pointer (such as an
-offset) to the actual data of the component, and this data is contiguous
-with the rest of the object, then the storage place attributes should
-reflect the place of the actual data, not the pointer.  If a component is
-allocated discontinuously from the rest of the object, then a warning
-should be generated upon reference to one of its storage place
-attributes.”
-@end quotation
-
-Followed.  There are no such components in GNAT.
-
-@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{232}
-@section RM 13.5.3(7-8): Bit Ordering
-
-
-@quotation
-
-“The recommended level of support for the non-default bit ordering is:
-
-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
-
-Followed.  Word size does not equal storage size in this implementation.
-Thus non-default bit ordering is not supported.
-
-@geindex Address
-@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{233}
-@section RM 13.7(37): Address as Private
-
-
-@quotation
-
-“@cite{Address} should be of a private type.”
-@end quotation
-
-Followed.
-
-@geindex Operations
-@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{234}
-@section RM 13.7.1(16): Address Operations
-
-
-@quotation
-
-“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 @code{Program_Error}.”
-@end quotation
-
-Followed.  Address arithmetic is modular arithmetic that wraps around.  No
-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{235}
-@section RM 13.9(14-17): Unchecked Conversion
-
-
-@quotation
-
-“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
-
-Followed.
-
-@quotation
-
-“The implementation should not generate unnecessary run-time checks to
-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.”
-@end quotation
-
-Followed.  There are no restrictions on unchecked conversion.  A warning is
-generated if the source and target types do not have the same size since
-the semantics in this case may be target dependent.
-
-@quotation
-
-“The recommended level of support for unchecked conversions is:
-
-Unchecked conversions should be supported and should be reversible in
-the cases where this clause defines the result.  To enable meaningful use
-of unchecked conversion, a contiguous representation should be used for
-elementary subtypes, for statically constrained array subtypes whose
-component subtype is one of the subtypes described in this paragraph,
-and for record subtypes without discriminants whose component subtypes
-are described in this paragraph.”
-@end quotation
-
-Followed.
-
-@geindex Heap usage
-@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{236}
-@section RM 13.11(23-25): Implicit Heap Usage
-
-
-@quotation
-
-“An implementation should document any cases in which it dynamically
-allocates heap storage for a purpose other than the evaluation of an
-allocator.”
-@end quotation
-
-Followed, the only other points at which heap storage is dynamically
-allocated are as follows:
-
-
-@itemize *
-
-@item 
-At initial elaboration time, to allocate dynamically sized global
-objects.
-
-@item 
-To allocate space for a task when a task is created.
-
-@item 
-To extend the secondary stack dynamically when needed.  The secondary
-stack is used for returning variable length results.
-@end itemize
-
-
-@quotation
-
-“A default (implementation-provided) storage pool for an
-access-to-constant type should not have overhead to support deallocation of
-individual objects.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“A storage pool for an anonymous access type should be created at the
-point of an allocator for the type, and be reclaimed when the designated
-object becomes inaccessible.”
-@end quotation
-
-Followed.
-
-@geindex Unchecked deallocation
-
-@node RM 13 11 2 17 Unchecked Deallocation,RM 13 13 2 1 6 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{237}
-@section RM 13.11.2(17): Unchecked Deallocation
-
-
-@quotation
-
-“For a standard storage pool, @code{Free} should actually reclaim the
-storage.”
-@end quotation
-
-Followed.
-
-@geindex Stream oriented attributes
-
-@node RM 13 13 2 1 6 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-1-6-stream-oriented-attributes}@anchor{238}
-@section RM 13.13.2(1.6): Stream Oriented Attributes
-
-
-@quotation
-
-“If not specified, the value of Stream_Size for an elementary type
-should be the number of bits that corresponds to the minimum number of
-stream elements required by the first subtype of the type, rounded up
-to the nearest factor or multiple of the word size that is also a
-multiple of the stream element size.”
-@end quotation
-
-Followed, except that the number of stream elements is 1, 2, 3, 4 or 8.
-The Stream_Size may be used to override the default choice.
-
-The default 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 @code{Read} and
-@code{Write}, which uses the target-independent XDR standard representation for
-scalar types. This XDR alternative can be enabled via the binder switch -xdr.
-
-@geindex XDR representation
-
-@geindex Read attribute
-
-@geindex Write attribute
-
-@geindex Stream oriented attributes
-
-@node RM A 1 52 Names of Predefined Numeric Types,RM A 3 2 49 Ada Characters Handling,RM 13 13 2 1 6 Stream Oriented Attributes,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{239}
-@section RM A.1(52): Names of Predefined Numeric Types
-
-
-@quotation
-
-“If an implementation provides additional named predefined integer types,
-then the names should end with @code{Integer} as in
-@code{Long_Integer}.  If an implementation provides additional named
-predefined floating point types, then the names should end with
-@code{Float} as in @code{Long_Float}.”
-@end quotation
-
-Followed.
-
-@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{23a}
-@section RM A.3.2(49): @code{Ada.Characters.Handling}
-
-
-@quotation
-
-“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
-
-Followed.  GNAT provides no such localized definitions.
-
-@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{23b}
-@section RM A.4.4(106): Bounded-Length String Handling
-
-
-@quotation
-
-“Bounded string objects should not be implemented by implicit pointers
-and dynamic allocation.”
-@end quotation
-
-Followed.  No implicit pointers or dynamic allocation are used.
-
-@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{23c}
-@section RM A.5.2(46-47): Random Number Generation
-
-
-@quotation
-
-“Any storage associated with an object of type @code{Generator} should be
-reclaimed on exit from the scope of the object.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“If the generator period is sufficiently long in relation to the number
-of distinct initiator values, then each possible value 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
-varying function of the initiator value.”
-@end quotation
-
-Followed.  The generator period is sufficiently long for the first
-condition here to hold true.
-
-@geindex Get_Immediate
-
-@node RM A 10 7 23 Get_Immediate,RM A 18 Containers,RM A 5 2 46-47 Random Number Generation,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{23d}
-@section RM A.10.7(23): @code{Get_Immediate}
-
-
-@quotation
-
-“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
-@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 @code{Get_Immediate} call. A special unit
-@code{Interfaces.Vxworks.IO} is provided that contains routines to enable
-this functionality.
-
-@geindex Containers
-
-@node RM A 18 Containers,RM B 1 39-41 Pragma Export,RM A 10 7 23 Get_Immediate,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-a-18-containers}@anchor{23e}
-@section RM A.18: @code{Containers}
-
-
-All implementation advice pertaining to Ada.Containers and its
-child units (that is, all implementation advice occurring within
-section A.18 and its subsections) is followed except for A.18.24(17):
-
-@quotation
-
-“Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. “
-@end quotation
-
-The implementations of the two Reference_Preserving_Key functions of
-the generic package Ada.Containers.Bounded_Ordered_Sets each currently make
-use of dynamic allocation; other operations on bounded ordered set objects
-follow the implementation advice.
-
-@geindex Export
-
-@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 18 Containers,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{23f}
-@section RM B.1(39-41): Pragma @code{Export}
-
-
-@quotation
-
-“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
-@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
-
-Followed.
-
-@quotation
-
-“Automatic elaboration of pre-elaborated packages should be
-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
-@code{adainit} must be called to elaborate pre-elaborated
-packages.
-
-@quotation
-
-“For each supported convention `L' other than @code{Intrinsic}, an
-implementation should support @code{Import} and @code{Export} pragmas
-for objects of `L'-compatible types and for subprograms, and pragma
-@cite{Convention} for `L'-eligible types and for subprograms,
-presuming the other language has corresponding features.  Pragma
-@code{Convention} need not be supported for scalar types.”
-@end quotation
-
-Followed.
-
-@geindex Package Interfaces
-
-@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{240}
-@section RM B.2(12-13): Package @code{Interfaces}
-
-
-@quotation
-
-“For each implementation-defined convention identifier, there should be a
-child package of package Interfaces with the corresponding name.  This
-package should contain any declarations that would be useful for
-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
-@code{Interfaces}.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An implementation supporting an interface to C, COBOL, or Fortran should
-provide the corresponding package or packages described in the following
-clauses.”
-@end quotation
-
-Followed.  GNAT provides all the packages described in this section.
-
-@geindex C
-@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{241}
-@section RM B.3(63-71): Interfacing with C
-
-
-@quotation
-
-“An implementation should support the following interface correspondences
-between Ada and C.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An Ada procedure corresponds to a void-returning C function.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An Ada function corresponds to a non-void C function.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An Ada @code{in} scalar parameter is passed as a scalar argument to a C
-function.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“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 @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 @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
-
-Followed.
-
-@quotation
-
-“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 @code{T}.”
-@end quotation
-
-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.
-
-@quotation
-
-“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 @code{T}.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An Ada parameter of an access-to-subprogram type is passed as a pointer
-to a C function whose prototype corresponds to the designated
-subprogram’s specification.”
-@end quotation
-
-Followed.
-
-@geindex COBOL
-@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{242}
-@section RM B.4(95-98): Interfacing with COBOL
-
-
-@quotation
-
-“An Ada implementation should support the following interface
-correspondences between Ada and COBOL.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“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.
-
-@quotation
-
-“An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of
-the corresponding COBOL type.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the
-COBOL type corresponding to the Ada parameter type; for scalars, a local
-copy is used if necessary to ensure by-copy semantics.”
-@end quotation
-
-Followed.
-
-@geindex Fortran
-@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{243}
-@section RM B.5(22-26): Interfacing with Fortran
-
-
-@quotation
-
-“An Ada implementation should support the following interface
-correspondences between Ada and Fortran:”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An Ada procedure corresponds to a Fortran subroutine.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An Ada function corresponds to a Fortran function.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“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
-necessary to ensure by-copy semantics.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“An Ada parameter of an access-to-subprogram type is passed as a
-reference to a Fortran procedure whose interface corresponds to the
-designated subprogram’s specification.”
-@end quotation
-
-Followed.
-
-@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{244}
-@section RM C.1(3-5): Access to Machine Operations
-
-
-@quotation
-
-“The machine code or intrinsic support should allow access to all
-operations normally available to assembly language programmers for the
-target environment, including privileged instructions, if any.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“The interfacing pragmas (see Annex B) should support interface to
-assembler; the default assembler should be associated with the
-convention identifier @code{Assembler}.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“If an entity is exported to assembly language, then the implementation
-should allocate it at an addressable location, and should ensure that it
-is retained by the linking process, even if not otherwise referenced
-from the Ada code.  The implementation should assume that any call to a
-machine code or assembler subprogram is allowed to read or update every
-object that is specified as exported.”
-@end quotation
-
-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{245}
-@section RM C.1(10-16): Access to Machine Operations
-
-
-@quotation
-
-“The implementation should ensure that little or no overhead is
-associated with calling intrinsic and machine-code subprograms.”
-@end quotation
-
-Followed for both intrinsics and machine-code subprograms.
-
-@quotation
-
-“It is recommended that intrinsic subprograms be provided for convenient
-access to any machine operations that provide special capabilities or
-efficiency and that are not otherwise available through the language
-constructs.”
-@end quotation
-
-Followed.  A full set of machine operation intrinsic subprograms is provided.
-
-@quotation
-
-“Atomic read-modify-write operations—e.g., test and set, compare and
-swap, decrement and test, enqueue/dequeue.”
-@end quotation
-
-Followed on any target supporting such operations.
-
-@quotation
-
-“Standard numeric functions—e.g.:, sin, log.”
-@end quotation
-
-Followed on any target supporting such operations.
-
-@quotation
-
-“String manipulation operations—e.g.:, translate and test.”
-@end quotation
-
-Followed on any target supporting such operations.
-
-@quotation
-
-“Vector operations—e.g.:, compare vector against thresholds.”
-@end quotation
-
-Followed on any target supporting such operations.
-
-@quotation
-
-“Direct operations on I/O ports.”
-@end quotation
-
-Followed on any target supporting such 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{246}
-@section RM C.3(28): Interrupt Support
-
-
-@quotation
-
-“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.”
-@end quotation
-
-Followed.  The underlying system does not allow for 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{247}
-@section RM C.3.1(20-21): Protected Procedure Handlers
-
-
-@quotation
-
-“Whenever possible, the implementation should allow interrupt handlers to
-be called directly by the hardware.”
-@end quotation
-
-Followed on any target where the underlying operating system permits
-such direct calls.
-
-@quotation
-
-“Whenever practical, violations of any
-implementation-defined restrictions should be detected before run time.”
-@end quotation
-
-Followed.  Compile time warnings are given when possible.
-
-@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{248}
-@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 @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
-
-Followed.
-
-@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{249}
-@section RM C.4(14): Pre-elaboration Requirements
-
-
-@quotation
-
-“It is recommended that pre-elaborated packages be implemented in such a
-way that there should be little or no code executed at run time for the
-elaboration of entities not already covered by the Implementation
-Requirements.”
-@end quotation
-
-Followed.  Executable code is generated in some cases, e.g., loops
-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{24a}
-@section RM C.5(8): Pragma @code{Discard_Names}
-
-
-@quotation
-
-“If the pragma applies to an entity, then the implementation should
-reduce the amount of storage used for storing names associated with that
-entity.”
-@end quotation
-
-Followed.
-
-@geindex Package Task_Attributes
-
-@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{24b}
-@section RM C.7.2(30): The Package Task_Attributes
-
-
-@quotation
-
-“Some implementations are targeted to domains in which memory use at run
-time must be completely deterministic.  For such implementations, it is
-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 @code{N}
-attribute objects, and the heap for the others.  In the latter case,
-@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{24c}
-@section RM D.3(17): Locking Policies
-
-
-@quotation
-
-“The implementation should use names that end with @code{_Locking} for
-locking policies defined by the implementation.”
-@end quotation
-
-Followed.  Two implementation-defined locking policies are defined,
-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{24d}
-@section RM D.4(16): Entry Queuing Policies
-
-
-@quotation
-
-“Names that end with @code{_Queuing} should be used
-for all implementation-defined queuing policies.”
-@end quotation
-
-Followed.  No such implementation-defined queuing policies exist.
-
-@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{24e}
-@section RM D.6(9-10): Preemptive Abort
-
-
-@quotation
-
-“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.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“On a multi-processor, the delay associated with aborting a task on
-another processor should be bounded; the implementation should use
-periodic polling, if necessary, to achieve this.”
-@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{24f}
-@section RM D.7(21): Tasking Restrictions
-
-
-@quotation
-
-“When feasible, the implementation should take advantage of the specified
-restrictions to produce a more efficient implementation.”
-@end quotation
-
-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 @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{250}
-@section RM D.8(47-49): Monotonic Time
-
-
-@quotation
-
-“When appropriate, implementations should provide configuration
-mechanisms to change the value of @code{Tick}.”
-@end quotation
-
-Such configuration mechanisms are not appropriate to this implementation
-and are thus not supported.
-
-@quotation
-
-“It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
-be implemented as transformations of the same time base.”
-@end quotation
-
-Followed.
-
-@quotation
-
-“It is recommended that the best time base which exists in
-the underlying system be available to the application through
-@code{Clock}.  @cite{Best} may mean highest accuracy or largest range.”
-@end quotation
-
-Followed.
-
-@geindex Partition communication subsystem
-
-@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{251}
-@section RM E.5(28-29): Partition Communication Subsystem
-
-
-@quotation
-
-“Whenever possible, the PCS on the called partition should allow for
-multiple tasks to call the RPC-receiver with different messages and
-should allow them to block until the corresponding subprogram body
-returns.”
-@end quotation
-
-Followed by GLADE, a separately supplied PCS that can be used with
-GNAT.
-
-@quotation
-
-“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
-GNAT.
-
-@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{252}
-@section RM F(7): COBOL Support
-
-
-@quotation
-
-“If COBOL (respectively, C) is widely supported in the target
-environment, implementations supporting the Information Systems Annex
-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
-
-Followed.
-
-@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{253}
-@section RM F.1(2): Decimal Radix Support
-
-
-@quotation
-
-“Packed decimal should be used as the internal representation for objects
-of subtype @code{S} when @code{S}’Machine_Radix = 10.”
-@end quotation
-
-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{254}
-@section RM G: Numerics
-
-
-@quotation
-
-“If Fortran (respectively, C) is widely supported in the target
-environment, implementations supporting the Numerics Annex
-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
-
-Followed.
-
-@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{255}
-@section RM G.1.1(56-58): Complex Types
-
-
-@quotation
-
-“Because the usual mathematical meaning of multiplication of a complex
-operand and a real operand is that of the scaling of both components of
-the former by the latter, an implementation should not perform this
-operation by first promoting the real operand to complex type and then
-performing a full complex multiplication.  In systems that, in the
-future, support an Ada binding to IEC 559:1989, the latter technique
-will not generate the required result when one of the components of the
-complex operand is infinite.  (Explicit multiplication of the infinite
-component by the zero component obtained during promotion yields a NaN
-that propagates into the final result.) Analogous advice applies in the
-case of multiplication of a complex operand and a pure-imaginary
-operand, and in the case of division of a complex operand by a real or
-pure-imaginary operand.”
-@end quotation
-
-Not followed.
-
-@quotation
-
-“Similarly, because the usual mathematical meaning of addition of a
-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 @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
-operand is a negatively signed zero.  (Explicit addition of the negative
-zero to the zero obtained during promotion yields a positive zero.)
-Analogous advice applies in the case of addition of a complex operand
-and a pure-imaginary operand, and in the case of subtraction of a
-complex operand and a real or pure-imaginary operand.”
-@end quotation
-
-Not followed.
-
-@quotation
-
-“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 @code{Argument}
-function should have the sign of the imaginary component of the
-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 @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
-
-Followed.
-
-@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{256}
-@section RM G.1.2(49): Complex Elementary Functions
-
-
-@quotation
-
-“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
-have the sign of the parameter component at the origin.  Other complex
-elementary functions have zero components whose sign is opposite that of
-a parameter component at the origin, or is always positive or always
-negative.”
-@end quotation
-
-Followed.
-
-@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{257}
-@section RM G.2.4(19): Accuracy Requirements
-
-
-@quotation
-
-“The versions of the forward trigonometric functions 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.  For the same reason, the
-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 accuracy
-
-@geindex Accuracy
-@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{258}
-@section RM G.2.6(15): Complex Arithmetic Accuracy
-
-
-@quotation
-
-“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
-
-Followed.
-
-@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{259}
-@section RM H.6(15/2): Pragma Partition_Elaboration_Policy
-
-
-@quotation
-
-“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.”
-@end quotation
-
-Not followed.
-
-@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top
-@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{25a}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{25b}@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}
-@chapter Implementation Defined Characteristics
-
-
-In addition to the implementation dependent pragmas and attributes, and the
-implementation advice, there are a number of other Ada features that are
-potentially implementation dependent and are designated as
-implementation-defined. These are mentioned throughout the Ada Reference
-Manual, and are summarized in Annex M.
-
-A requirement for conforming Ada compilers is that they provide
-documentation describing how the implementation deals with each of these
-issues.  In this chapter you will find each point in Annex M listed,
-followed by a description of how GNAT handles the implementation dependence.
-
-You can use this chapter as a guide to minimizing implementation
-dependent features in your programs if portability to other compilers
-and other operating systems is an important consideration.  The numbers
-in each entry below correspond to the paragraph numbers in the Ada
-Reference Manual.
-
-
-@itemize *
-
-@item 
-“Whether or not each recommendation given in Implementation
-Advice is followed.  See 1.1.2(37).”
-@end itemize
-
-See @ref{a,,Implementation Advice}.
-
-
-@itemize *
-
-@item 
-“Capacity limitations of the implementation.  See 1.1.3(3).”
-@end itemize
-
-The complexity of programs that can be processed is limited only by the
-total amount of available virtual memory, and disk space for the
-generated object files.
-
-
-@itemize *
-
-@item 
-“Variations from the standard that are impractical to avoid
-given the implementation’s execution environment.  See 1.1.3(6).”
-@end itemize
-
-There are no variations from the standard.
-
-
-@itemize *
-
-@item 
-“Which code_statements cause external
-interactions.  See 1.1.3(10).”
-@end itemize
-
-Any `code_statement' can potentially cause external interactions.
-
-
-@itemize *
-
-@item 
-“The coded representation for the text of an Ada
-program.  See 2.1(4).”
-@end itemize
-
-See separate section on source representation.
-
-
-@itemize *
-
-@item 
-“The semantics of an Ada program whose text is not in
-Normalization Form C.  See 2.1(4).”
-@end itemize
-
-See separate section on source representation.
-
-
-@itemize *
-
-@item 
-“The representation for an end of line.  See 2.2(2).”
-@end itemize
-
-See separate section on source representation.
-
-
-@itemize *
-
-@item 
-“Maximum supported line length and lexical element
-length.  See 2.2(15).”
-@end itemize
-
-The maximum line length is 255 characters and the maximum length of
-a lexical element is also 255 characters. This is the default setting
-if not overridden by the use of compiler switch `-gnaty' (which
-sets the maximum to 79) or `-gnatyMnn' which allows the maximum
-line length to be specified to be any value up to 32767. The maximum
-length of a lexical element is the same as the maximum line length.
-
-
-@itemize *
-
-@item 
-“Implementation defined pragmas.  See 2.8(14).”
-@end itemize
-
-See @ref{7,,Implementation Defined Pragmas}.
-
-
-@itemize *
-
-@item 
-“Effect of pragma @code{Optimize}.  See 2.8(27).”
-@end itemize
-
-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.
-
-
-@itemize *
-
-@item 
-“The message string associated with the Assertion_Error exception raised
-by the failure of a predicate check if there is no applicable
-Predicate_Failure aspect.  See 3.2.4(31).”
-@end itemize
-
-In the case of a Dynamic_Predicate aspect, the string is
-“Dynamic_Predicate failed at <source position>”, where
-“<source position>” might be something like “foo.adb:123”.
-The Static_Predicate case is handled analogously.
-
-
-@itemize *
-
-@item 
-“The predefined integer types declared in
-@code{Standard}.  See 3.5.4(25).”
-@end itemize
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@headitem
-
-Type
-
-@tab
-
-Representation
-
-@item
-
-`Short_Short_Integer'
-
-@tab
-
-8-bit signed
-
-@item
-
-`Short_Integer'
-
-@tab
-
-16-bit signed
-
-@item
-
-`Integer'
-
-@tab
-
-32-bit signed
-
-@item
-
-`Long_Integer'
-
-@tab
-
-64-bit signed (on most 64-bit targets,
-depending on the C definition of long)
-32-bit signed (on all other targets)
-
-@item
-
-`Long_Long_Integer'
-
-@tab
-
-64-bit signed
-
-@item
-
-`Long_Long_Long_Integer'
-
-@tab
-
-128-bit signed (on 64-bit targets)
-64-bit signed (on 32-bit targets)
-
-@end multitable
-
-
-
-@itemize *
-
-@item 
-“Any nonstandard integer types and the operators defined
-for them.  See 3.5.4(26).”
-@end itemize
-
-There are no nonstandard integer types.
-
-
-@itemize *
-
-@item 
-“Any nonstandard real types and the operators defined for
-them.  See 3.5.6(8).”
-@end itemize
-
-There are no nonstandard real types.
-
-
-@itemize *
-
-@item 
-“What combinations of requested decimal precision and range
-are supported for floating point types.  See 3.5.7(7).”
-@end itemize
-
-The precision and range are defined by the IEEE Standard for Floating-Point
-Arithmetic (IEEE 754-2019).
-
-
-@itemize *
-
-@item 
-“The predefined floating point types declared in
-@code{Standard}.  See 3.5.7(16).”
-@end itemize
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@headitem
-
-Type
-
-@tab
-
-Representation
-
-@item
-
-`Short_Float'
-
-@tab
-
-IEEE Binary32 (Single)
-
-@item
-
-`Float'
-
-@tab
-
-IEEE Binary32 (Single)
-
-@item
-
-`Long_Float'
-
-@tab
-
-IEEE Binary64 (Double)
-
-@item
-
-`Long_Long_Float'
-
-@tab
-
-IEEE Binary64 (Double) on non-x86 architectures
-IEEE 80-bit Extended on x86 architecture
-
-@end multitable
-
-
-The default rounding mode specified by the IEEE 754 Standard is assumed both
-for static and dynamic computations (that is, round to nearest, ties to even).
-The input routines yield correctly rounded values for Short_Float, Float, and
-Long_Float at least. The output routines can compute up to twice as many exact
-digits as the value of @code{T'Digits} for any type, for example 30 digits for
-Long_Float; if more digits are requested, zeros are printed.
-
-
-@itemize *
-
-@item 
-“The small of an ordinary fixed point type.  See 3.5.9(8).”
-@end itemize
-
-The small is the largest power of two that does not exceed the delta.
-
-
-@itemize *
-
-@item 
-“What combinations of small, range, and digits are
-supported for fixed point types.  See 3.5.9(10).”
-@end itemize
-
-For an ordinary fixed point type, on 32-bit platforms, the small must lie in
-2.0**(-80) .. 2.0**80 and the range in -9.0E+36 .. 9.0E+36; any combination
-is permitted that does not result in a mantissa larger than 63 bits.
-
-On 64-bit platforms, the small must lie in 2.0**(-127) .. 2.0**127 and the
-range in -1.0E+76 .. 1.0E+76; any combination is permitted that does not
-result in a mantissa larger than 63 bits, and any combination is permitted
-that results in a mantissa between 64 and 127 bits if the small is the
-ratio of two integers that lie in 1 .. 2.0**127.
-
-If the small is the ratio of two integers with 64-bit magnitude on 32-bit
-platforms and 128-bit magnitude on 64-bit platforms, which is the case if
-no @code{small} clause is provided, then the operations of the fixed point
-type are entirely implemented by means of integer instructions.  In the
-other cases, some operations, in particular input and output, may be
-implemented by means of floating-point instructions and may be affected
-by accuracy issues on architectures other than x86.
-
-For a decimal fixed point type, on 32-bit platforms, the small must lie in
-1.0E-18 .. 1.0E+18 and the digits in 1 .. 18.  On 64-bit platforms, the
-small must lie in 1.0E-38 .. 1.0E+38 and the digits in 1 .. 38.
-
-
-@itemize *
-
-@item 
-“The result of @code{Tags.Expanded_Name} for types declared
-within an unnamed `block_statement'.  See 3.9(10).”
-@end itemize
-
-Block numbers of the form @code{B@var{nnn}}, where `nnn' is a
-decimal integer are allocated.
-
-
-@itemize *
-
-@item 
-“The sequence of characters of the value returned by Tags.Expanded_Name
-(respectively, Tags.Wide_Expanded_Name) when some of the graphic
-characters of Tags.Wide_Wide_Expanded_Name are not defined in Character
-(respectively, Wide_Character).  See 3.9(10.1).”
-@end itemize
-
-This is handled in the same way as the implementation-defined behavior
-referenced in A.4.12(34).
-
-
-@itemize *
-
-@item 
-“Implementation-defined attributes.  See 4.1.4(12).”
-@end itemize
-
-See @ref{8,,Implementation Defined Attributes}.
-
-
-@itemize *
-
-@item 
-“The value of the parameter to Empty for some container aggregates.
-See 4.3.5(40).”
-@end itemize
-
-As per the suggestion given in the Annotated Ada RM, the default value
-of the formal parameter is used if one exists and zero is used otherwise.
-
-
-@itemize *
-
-@item 
-“The maximum number of chunks for a parallel reduction expression without
-a chunk_specification.  See 4.5.10(21).”
-@end itemize
-
-Feature unimplemented.
-
-
-@itemize *
-
-@item 
-“Rounding of real static expressions which are exactly half-way between
-two machine numbers.  See 4.9(38).”
-@end itemize
-
-Round to even is used in all such cases.
-
-
-@itemize *
-
-@item 
-“The maximum number of chunks for a parallel generalized iterator without
-a chunk_specification.  See 5.5.2(10).”
-@end itemize
-
-Feature unimplemented.
-
-
-@itemize *
-
-@item 
-“The number of chunks for an array component iterator.  See 5.5.2(11).”
-@end itemize
-
-Feature unimplemented.
-
-
-@itemize *
-
-@item 
-“Any extensions of the Global aspect.  See 6.1.2(43).”
-@end itemize
-
-Feature unimplemented.
-
-
-@itemize *
-
-@item 
-“The circumstances the implementation passes in the null value for a view
-conversion of an access type used as an out parameter.  See 6.4.1(19).”
-@end itemize
-
-Difficult to characterize.
-
-
-@itemize *
-
-@item 
-“Any extensions of the Default_Initial_Condition aspect.  See 7.3.3(11).”
-@end itemize
-
-SPARK allows specifying `null' as the Default_Initial_Condition
-aspect of a type. See the SPARK reference manual for further details.
-
-
-@itemize *
-
-@item 
-“Any implementation-defined time types.  See 9.6(6).”
-@end itemize
-
-There are no implementation-defined time types.
-
-
-@itemize *
-
-@item 
-“The time base associated with relative delays.  See 9.6(20).”
-@end itemize
-
-See 9.6(20).  The time base used is that provided by the C library
-function @code{gettimeofday}.
-
-
-@itemize *
-
-@item 
-“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
-@code{gettimeofday}.
-
-
-@itemize *
-
-@item 
-“The time zone used for package @code{Calendar}
-operations.  See 9.6(24).”
-@end itemize
-
-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
-@code{localtime}.
-
-
-@itemize *
-
-@item 
-“Any limit on `delay_until_statements' of
-`select_statements'.  See 9.6(29).”
-@end itemize
-
-There are no such limits.
-
-
-@itemize *
-
-@item 
-“The result of Calendar.Formatting.Image if its argument represents more
-than 100 hours.  See 9.6.1(86).”
-@end itemize
-
-Calendar.Time_Error is raised.
-
-
-@itemize *
-
-@item 
-“Implementation-defined conflict check policies.  See 9.10.1(5).”
-@end itemize
-
-There are no implementation-defined conflict check policies.
-
-
-@itemize *
-
-@item 
-“The representation for a compilation.  See 10.1(2).”
-@end itemize
-
-A compilation is represented by a sequence of files presented to the
-compiler in a single invocation of the `gcc' command.
-
-
-@itemize *
-
-@item 
-“Any restrictions on compilations that contain multiple
-compilation_units.  See 10.1(4).”
-@end itemize
-
-No single file can contain more than one compilation unit, but any
-sequence of files can be presented to the compiler as a single
-compilation.
-
-
-@itemize *
-
-@item 
-“The mechanisms for creating an environment and for adding
-and replacing compilation units.  See 10.1.4(3).”
-@end itemize
-
-See separate section on compilation model.
-
-
-@itemize *
-
-@item 
-“The manner of explicitly assigning library units to a
-partition.  See 10.2(2).”
-@end itemize
-
-If a unit contains an Ada main program, then the Ada units for the partition
-are determined by recursive application of the rules in the Ada Reference
-Manual section 10.2(2-6).  In other words, the Ada units will be those that
-are needed by the main program, and then this definition of need is applied
-recursively to those units, and the partition contains the transitive
-closure determined by this relationship.  In short, all the necessary units
-are included, with no need to explicitly specify the list.  If additional
-units are required, e.g., by foreign language units, then all units must be
-mentioned in the context clause of one of the needed Ada units.
-
-If the partition contains no main program, or if the main program is in
-a language other than Ada, then GNAT
-provides the binder options `-z' and `-n' respectively, and in
-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 `GNAT Make Program gnatmake' in the
-@cite{GNAT User’s Guide}.
-
-
-@itemize *
-
-@item 
-“The implementation-defined means, if any, of specifying which compilation
-units are needed by a given compilation unit.  See 10.2(2).”
-@end itemize
-
-The units needed by a given compilation unit are as defined in
-the Ada Reference Manual section 10.2(2-6).  There are no
-implementation-defined pragmas or other implementation-defined
-means for specifying needed units.
-
-
-@itemize *
-
-@item 
-“The manner of designating the main subprogram of a
-partition.  See 10.2(7).”
-@end itemize
-
-The main program is designated by providing the name of the
-corresponding @code{ALI} file as the input parameter to the binder.
-
-
-@itemize *
-
-@item 
-“The order of elaboration of `library_items'.  See 10.2(18).”
-@end itemize
-
-The first constraint on ordering is that it meets the requirements of
-Chapter 10 of the Ada Reference Manual.  This still leaves some
-implementation-dependent choices, which are resolved by analyzing
-the elaboration code of each unit and identifying implicit
-elaboration-order dependencies.
-
-
-@itemize *
-
-@item 
-“Parameter passing and function return for the main
-subprogram.  See 10.2(21).”
-@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 @code{Ada.Command_Line.Set_Exit_Status}).
-
-
-@itemize *
-
-@item 
-“The mechanisms for building and running partitions.  See 10.2(24).”
-@end itemize
-
-GNAT itself supports programs with only a single partition. The GNATDIST
-tool provided with the GLADE package (which also includes an implementation
-of the PCS) provides a completely flexible method for building and running
-programs consisting of multiple partitions. See the separate GLADE manual
-for details.
-
-
-@itemize *
-
-@item 
-“The details of program execution, including program
-termination.  See 10.2(25).”
-@end itemize
-
-See separate section on compilation model.
-
-
-@itemize *
-
-@item 
-“The semantics of any non-active partitions supported by the
-implementation.  See 10.2(28).”
-@end itemize
-
-Passive partitions are supported on targets where shared memory is
-provided by the operating system. See the GLADE reference manual for
-further details.
-
-
-@itemize *
-
-@item 
-“The information returned by @code{Exception_Message}.  See 11.4.1(10).”
-@end itemize
-
-Exception message returns the null string unless a specific message has
-been passed by the program.
-
-
-@itemize *
-
-@item 
-“The result of @code{Exceptions.Exception_Name} for types
-declared within an unnamed `block_statement'.  See 11.4.1(12).”
-@end itemize
-
-Blocks have implementation defined names of the form @code{B@var{nnn}}
-where `nnn' is an integer.
-
-
-@itemize *
-
-@item 
-“The information returned by
-@code{Exception_Information}.  See 11.4.1(13).”
-@end itemize
-
-@code{Exception_Information} returns a string in the following format:
-
-@example
-*Exception_Name:* nnnnn
-*Message:* mmmmm
-*PID:* ppp
-*Load address:* 0xhhhh
-*Call stack traceback locations:*
-0xhhhh 0xhhhh 0xhhhh ... 0xhhh
-@end example
-
-where
-
-@quotation
-
-
-@itemize *
-
-@item 
-@code{nnnn} is the fully qualified name of the exception in all upper
-case letters. This line is always present.
-
-@item 
-@code{mmmm} is the message (this line present only if message is non-null)
-
-@item 
-@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.
-
-@item 
-The Load address line, the Call stack traceback locations line and the
-following values are present only if at least one traceback location was
-recorded. The Load address indicates the address at which the main executable
-was loaded; this line may not be present if operating system hasn’t relocated
-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 @code{LF} character (@code{16#0A#}).
-@end itemize
-@end quotation
-
-
-@itemize *
-
-@item 
-“The sequence of characters of the value returned by
-Exceptions.Exception_Name (respectively, Exceptions.Wide_Exception_Name)
-when some of the graphic characters of Exceptions.Wide_Wide_Exception_Name
-are not defined in Character (respectively, Wide_Character).
-See 11.4.1(12.1).”
-@end itemize
-
-This is handled in the same way as the implementation-defined behavior
-referenced in A.4.12(34).
-
-
-@itemize *
-
-@item 
-“The information returned by Exception_Information.  See 11.4.1(13).”
-@end itemize
-
-The exception name and the source location at which the exception was
-raised are included.
-
-
-@itemize *
-
-@item 
-“Implementation-defined policy_identifiers and assertion_aspect_marks
-allowed in a pragma Assertion_Policy.  See 11.4.2(9).”
-@end itemize
-
-Implementation-defined assertion_aspect_marks include Assert_And_Cut,
-Assume, Contract_Cases, Debug, Ghost, Initial_Condition, Loop_Invariant,
-Loop_Variant, Postcondition, Precondition, Predicate, Refined_Post,
-Statement_Assertions, and Subprogram_Variant. Implementation-defined
-policy_identifiers include Ignore and Suppressible.
-
-
-@itemize *
-
-@item 
-“The default assertion policy.  See 11.4.2(10).”
-@end itemize
-
-The default assertion policy is Ignore, although this can be overridden
-via compiler switches such as “-gnata”.
-
-
-@itemize *
-
-@item 
-“Implementation-defined check names.  See 11.5(27).”
-@end itemize
-
-The implementation defined check names include Alignment_Check,
-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 @code{Suppress} for full details.
-
-
-@itemize *
-
-@item 
-“Existence and meaning of second parameter of pragma Unsuppress.
-See 11.5(27.1).”
-@end itemize
-
-The legality rules for and semantics of the second parameter of pragma
-Unsuppress match those for the second argument of pragma Suppress.
-
-
-@itemize *
-
-@item 
-“The cases that cause conflicts between the representation of the
-ancestors of a type_declaration.  See 13.1(13.1).”
-@end itemize
-
-No such cases exist.
-
-
-@itemize *
-
-@item 
-“The interpretation of each representation aspect.  See 13.1(20).”
-@end itemize
-
-See separate section on data representations.
-
-
-@itemize *
-
-@item 
-“Any restrictions placed upon the specification of representation aspects.
-See 13.1(20).”
-@end itemize
-
-See separate section on data representations.
-
-
-@itemize *
-
-@item 
-“Implementation-defined aspects, including the syntax for specifying
-such aspects and the legality rules for such aspects.  See 13.1.1(38).”
-@end itemize
-
-See @ref{120,,Implementation Defined Aspects}.
-
-
-@itemize *
-
-@item 
-“The set of machine scalars.  See 13.3(8.1).”
-@end itemize
-
-See separate section on data representations.
-
-
-@itemize *
-
-@item 
-“The meaning of @code{Size} for indefinite subtypes.  See 13.3(48).”
-@end itemize
-
-The Size attribute of an indefinite subtype is not less than the Size
-attribute of any object of that type.
-
-
-@itemize *
-
-@item 
-“The meaning of Object_Size for indefinite subtypes.  See 13.3(58).”
-@end itemize
-
-The Object_Size attribute of an indefinite subtype is not less than the
-Object_Size attribute of any object of that type.
-
-
-@itemize *
-
-@item 
-“The default external representation for a type tag.  See 13.3(75).”
-@end itemize
-
-The default external representation for a type tag is the fully expanded
-name of the type in upper case letters.
-
-
-@itemize *
-
-@item 
-“What determines whether a compilation unit is the same in
-two different partitions.  See 13.3(76).”
-@end itemize
-
-A compilation unit is the same in two different partitions if and only
-if it derives from the same source file.
-
-
-@itemize *
-
-@item 
-“Implementation-defined components.  See 13.5.1(15).”
-@end itemize
-
-The only implementation defined component is the tag for a tagged type,
-which contains a pointer to the dispatching table.
-
-
-@itemize *
-
-@item 
-“If @code{Word_Size} = @code{Storage_Unit}, the default bit
-ordering.  See 13.5.3(5).”
-@end itemize
-
-@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 @code{System}.  See 13.7(2).”
-@end itemize
-
-See the definition of package System in @code{system.ads}.
-Note that two declarations are added to package System.
-
-@example
-Max_Priority           : constant Positive := Priority'Last;
-Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last;
-@end example
-
-
-@itemize *
-
-@item 
-“The range of Storage_Elements.Storage_Offset, the modulus of
-Storage_Elements.Storage_Element, and the declaration of
-Storage_Elements.Integer_Address.  See 13.7.1(11).”
-@end itemize
-
-See the definition of package System.Storage_Elements in @code{s-stoele.ads}.
-
-
-@itemize *
-
-@item 
-“The contents of the visible part of package @code{System.Machine_Code},
-and the meaning of `code_statements'.  See 13.8(7).”
-@end itemize
-
-See the definition and documentation in file @code{s-maccod.ads}.
-
-
-@itemize *
-
-@item 
-“The result of unchecked conversion for instances with scalar result
-types whose result is not defined by the language.  See 13.9(11).”
-@end itemize
-
-Unchecked conversion between types of the same size
-results in an uninterpreted transmission of the bits from one type
-to the other.  If the types are of unequal sizes, then in the case of
-discrete types, a shorter source is first zero or sign extended as
-necessary, and a shorter target is simply truncated on the left.
-For all non-discrete types, the source is first copied if necessary
-to ensure that the alignment requirements of the target are met, then
-a pointer is constructed to the source value, and the result is obtained
-by dereferencing this pointer after converting it to be a pointer to the
-target type. Unchecked conversions where the target subtype is an
-unconstrained array are not permitted. If the target alignment is
-greater than the source alignment, then a copy of the result is
-made with appropriate alignment
-
-
-@itemize *
-
-@item 
-“The result of unchecked conversion for instances with nonscalar result
-types whose result is not defined by the language.  See 13.9(11).”
-@end itemize
-
-See preceding definition for the scalar result case.
-
-
-@itemize *
-
-@item 
-“Whether or not the implementation provides user-accessible
-names for the standard pool type(s).  See 13.11(17).”
-@end itemize
-
-There are 3 different standard pools used by the compiler when
-@code{Storage_Pool} is not specified depending whether the type is local
-to a subprogram or defined at the library level and whether
-@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.  All these pools are accessible by means of @cite{with}ing
-these units.
-
-
-@itemize *
-
-@item 
-“The meaning of @code{Storage_Size} when neither the Storage_Size nor the
-Storage_Pool is specified for an access type.  See 13.11(18).”
-@end itemize
-
-@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.
-
-
-@itemize *
-
-@item 
-“The effect of specifying aspect Default_Storage_Pool on an instance
-of a language-defined generic unit.  See 13.11.3(5).”
-@end itemize
-
-Instances of language-defined generic units are treated the same as other
-instances with respect to the Default_Storage_Pool aspect.
-
-
-@itemize *
-
-@item 
-“Implementation-defined restrictions allowed in a pragma
-@code{Restrictions}.  See 13.12(8.7).”
-@end itemize
-
-See @ref{9,,Standard and Implementation Defined Restrictions}.
-
-
-@itemize *
-
-@item 
-“The consequences of violating limitations on
-@code{Restrictions} pragmas.  See 13.12(9).”
-@end itemize
-
-Restrictions that can be checked at compile time are enforced at
-compile time; violations are illegal. For other restrictions, any
-violation during program execution results in erroneous execution.
-
-
-@itemize *
-
-@item 
-“Implementation-defined usage profiles allowed in a pragma Profile.
-See 13.12(15).”
-@end itemize
-
-See @ref{7,,Implementation Defined Pragmas}.
-
-
-@itemize *
-
-@item 
-“The contents of the stream elements read and written by the Read and
-Write attributes of elementary types.  See 13.13.2(9).”
-@end itemize
-
-The representation is the in-memory representation of the base type of
-the type, using the number of bits corresponding to the
-@code{type'Size} value, and the natural ordering of the machine.
-
-
-@itemize *
-
-@item 
-“The names and characteristics of the numeric subtypes
-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 values returned by Strings.Hash.  See A.4.9(3).”
-@end itemize
-
-This hash function has predictable collisions and is subject to
-equivalent substring attacks. It is not suitable for construction of a
-hash table keyed on possibly malicious user input.
-
-
-@itemize *
-
-@item 
-“The value returned by a call to a Text_Buffer Get procedure if any
-character in the returned sequence is not defined in Character.
-See A.4.12(34).”
-@end itemize
-
-The contents of a buffer is represented internally as a UTF_8 string.
-The value return by Text_Buffer.Get is the result of passing that
-UTF_8 string to UTF_Encoding.Strings.Decode.
-
-
-@itemize *
-
-@item 
-“The value returned by a call to a Text_Buffer Wide_Get procedure if
-any character in the returned sequence is not defined in Wide_Character.
-See A.4.12(34).”
-@end itemize
-
-The contents of a buffer is represented internally as a UTF_8 string.
-The value return by Text_Buffer.Wide_Get is the result of passing that
-UTF_8 string to UTF_Encoding.Wide_Strings.Decode.
-
-
-@itemize *
-
-@item 
-“The accuracy actually achieved by the elementary
-functions.  See A.5.1(1).”
-@end itemize
-
-The elementary functions correspond to the functions available in the C
-library.  Only fast math mode is implemented.
-
-
-@itemize *
-
-@item 
-“The sign of a zero result from some of the operators or
-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
-floating-point.
-
-
-@itemize *
-
-@item 
-“The value of
-@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}.
-
-
-@itemize *
-
-@item 
-“The value of
-@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 string representation of a random number generator’s
-state.  See A.5.2(38).”
-@end itemize
-
-The value returned by the Image function is the concatenation of
-the fixed-width decimal representations of the 624 32-bit integers
-of the state vector.
-
-
-@itemize *
-
-@item 
-“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
-
-Running the compiler with `-gnatS' to produce a listing of package
-@code{Standard} displays the values of these attributes.
-
-
-@itemize *
-
-@item 
-“The value of @code{Buffer_Size} in @code{Storage_IO}.  See A.9(10).”
-@end itemize
-
-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 
-“External files for standard input, standard output, and
-standard error See A.10(5).”
-@end itemize
-
-These files are mapped onto the files provided by the C streams
-libraries. See source file @code{i-cstrea.ads} for further details.
-
-
-@itemize *
-
-@item 
-“The accuracy of the value produced by @code{Put}.  See A.10.9(36).”
-@end itemize
-
-If more digits are requested in the output than are represented by the
-precision of the value, zeroes are output in the corresponding least
-significant digit positions.
-
-
-@itemize *
-
-@item 
-“Current size for a stream file for which positioning is not supported.
-See A.12.1(1.1).”
-@end itemize
-
-Positioning is supported.
-
-
-@itemize *
-
-@item 
-“The meaning of @code{Argument_Count}, @code{Argument}, and
-@code{Command_Name}.  See A.15(1).”
-@end itemize
-
-These are mapped onto the @code{argv} and @code{argc} parameters of the
-main program in the natural manner.
-
-
-@itemize *
-
-@item 
-“The interpretation of file names and directory names.  See A.16(46).”
-@end itemize
-
-These names are interpreted consistently with the underlying file system.
-
-
-@itemize *
-
-@item 
-“The maxium value for a file size in Directories.  See A.16(87).”
-@end itemize
-
-Directories.File_Size’Last is equal to Long_Long_Integer’Last .
-
-
-@itemize *
-
-@item 
-“The result for Directories.Size for a directory or special file.
-See A.16(93).”
-@end itemize
-
-Name_Error is raised.
-
-
-@itemize *
-
-@item 
-“The result for Directories.Modification_Time for a directory or special file.
-See A.16(93).”
-@end itemize
-
-Name_Error is raised.
-
-
-@itemize *
-
-@item 
-“The interpretation of a nonnull search pattern in Directories.
-See A.16(104).”
-@end itemize
-
-When the @code{Pattern} parameter is not the null string, it is interpreted
-according to the syntax of regular expressions as defined in the
-@code{GNAT.Regexp} package.
-
-See @ref{25c,,GNAT.Regexp (g-regexp.ads)}.
-
-
-@itemize *
-
-@item 
-“The results of a Directories search if the contents of the directory are
-altered while a search is in progress.  See A.16(110).”
-@end itemize
-
-The effect of a call to Get_Next_Entry is determined by the current
-state of the directory.
-
-
-@itemize *
-
-@item 
-“The definition and meaning of an environment variable.  See A.17(1).”
-@end itemize
-
-This definition is determined by the underlying operating system.
-
-
-@itemize *
-
-@item 
-“The circumstances where an environment variable cannot be defined.
-See A.17(16).”
-
-There are no such implementation-defined circumstances.
-
-@item 
-“Environment names for which Set has the effect of Clear.  See A.17(17).”
-@end itemize
-
-There are no such names.
-
-
-@itemize *
-
-@item 
-“The value of Containers.Hash_Type’Modulus. The value of
-Containers.Count_Type’Last.  See A.18.1(7).”
-@end itemize
-
-Containers.Hash_Type’Modulus is 2**32.
-Containers.Count_Type’Last is 2**31 - 1.
-
-
-@itemize *
-
-@item 
-“Implementation-defined convention names.  See B.1(11).”
-@end itemize
-
-The following convention names are supported
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@headitem
-
-Convention Name
-
-@tab
-
-Interpretation
-
-@item
-
-`Ada'
-
-@tab
-
-Ada
-
-@item
-
-`Ada_Pass_By_Copy'
-
-@tab
-
-Allowed for any types except by-reference types such as limited
-records. Compatible with convention Ada, but causes any parameters
-with this convention to be passed by copy.
-
-@item
-
-`Ada_Pass_By_Reference'
-
-@tab
-
-Allowed for any types except by-copy types such as scalars.
-Compatible with convention Ada, but causes any parameters
-with this convention to be passed by reference.
-
-@item
-
-`Assembler'
-
-@tab
-
-Assembly language
-
-@item
-
-`Asm'
-
-@tab
-
-Synonym for Assembler
-
-@item
-
-`Assembly'
-
-@tab
-
-Synonym for Assembler
-
-@item
-
-`C'
-
-@tab
-
-C
-
-@item
-
-`C_Pass_By_Copy'
-
-@tab
-
-Allowed only for record types, like C, but also notes that record
-is to be passed by copy rather than reference.
-
-@item
-
-`COBOL'
-
-@tab
-
-COBOL
-
-@item
-
-`C_Plus_Plus (or CPP)'
-
-@tab
-
-C++
-
-@item
-
-`Default'
-
-@tab
-
-Treated the same as C
-
-@item
-
-`External'
-
-@tab
-
-Treated the same as C
-
-@item
-
-`Fortran'
-
-@tab
-
-Fortran
-
-@item
-
-`Intrinsic'
-
-@tab
-
-For support of pragma @code{Import} with convention Intrinsic, see
-separate section on Intrinsic Subprograms.
-
-@item
-
-`Stdcall'
-
-@tab
-
-Stdcall (used for Windows implementations only).  This convention correspond
-to the WINAPI (previously called Pascal convention) C/C++ convention under
-Windows.  A routine with this convention cleans the stack before
-exit. This pragma cannot be applied to a dispatching call.
-
-@item
-
-`DLL'
-
-@tab
-
-Synonym for Stdcall
-
-@item
-
-`Win32'
-
-@tab
-
-Synonym for Stdcall
-
-@item
-
-`Stubbed'
-
-@tab
-
-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 @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
-treated as being synonymous with convention C.  In all implementations,
-use of such other names results in a warning.
-
-@end multitable
-
-
-
-@itemize *
-
-@item 
-“The meaning of link names.  See B.1(36).”
-@end itemize
-
-Link names are the actual names used by the linker.
-
-
-@itemize *
-
-@item 
-“The manner of choosing link names when neither the link name nor the
-address of an imported or exported entity is specified.  See B.1(36).”
-@end itemize
-
-The default linker name is that which would be assigned by the relevant
-external language, interpreting the Ada name as being in all lower case
-letters.
-
-
-@itemize *
-
-@item 
-“The effect of pragma @code{Linker_Options}.  See B.1(37).”
-@end itemize
-
-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
-
-@example
-pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
-@end example
-
-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
-from the corresponding package spec.
-
-
-@itemize *
-
-@item 
-“The contents of the visible part of package
-@code{Interfaces} and its language-defined descendants.  See B.2(1).”
-@end itemize
-
-See files with prefix @code{i-} in the distributed library.
-
-
-@itemize *
-
-@item 
-“Implementation-defined children of package
-@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 definitions of certain types and constants in Interfaces.C.
-See B.3(41).”
-@end itemize
-
-See source file @code{i-c.ads}.
-
-
-@itemize *
-
-@item 
-“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
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@headitem
-
-COBOL
-
-@tab
-
-Ada
-
-@item
-
-`Floating'
-
-@tab
-
-Float
-
-@item
-
-`Long_Floating'
-
-@tab
-
-(Floating) Long_Float
-
-@item
-
-`Binary'
-
-@tab
-
-Integer
-
-@item
-
-`Long_Binary'
-
-@tab
-
-Long_Long_Integer
-
-@item
-
-`Decimal_Element'
-
-@tab
-
-Character
-
-@item
-
-`COBOL_Character'
-
-@tab
-
-Character
-
-@end multitable
-
-
-For initialization, see the file @code{i-cobol.ads} in the distributed library.
-
-
-@itemize *
-
-@item 
-“The types Fortran_Integer, Real, Double_Precision, and Character_Set
-in Interfaces.Fortran.  See B.5(17).”
-@end itemize
-
-See source file @code{i-fortra.ads}. These types are derived, respectively,
-from Integer, Float, Long_Float, and Character.
-
-
-@itemize *
-
-@item 
-“Implementation-defined intrinsic subprograms.  See C.1(1).”
-@end itemize
-
-See separate section on Intrinsic Subprograms.
-
-
-@itemize *
-
-@item 
-“Any restrictions on a protected procedure or its containing type when an
-aspect Attach_handler or Interrupt_Handler is specified.  See C.3.1(17).”
-@end itemize
-
-There are no such restrictions.
-
-
-@itemize *
-
-@item 
-“Any other forms of interrupt handler supported by the Attach_Handler and
-Interrupt_Handler aspects.  See C.3.1(19).”
-@end itemize
-
-There are no such forms.
-
-
-@itemize *
-
-@item 
-“The semantics of some attributes and functions of an entity for which
-aspect Discard_Names is True.  See C.5(7).”
-@end itemize
-
-If Discard_Names is True for an enumeration type, the Image attribute
-provides the image of the Pos of the literal, and Value accepts
-Pos values.
-
-If both of the aspects`@w{`}Discard_Names`@w{`} and @code{No_Tagged_Streams} are true
-for a tagged type, its Expanded_Name and External_Tag values are
-empty strings. This is useful to avoid exposing entity names at binary
-level.
-
-
-@itemize *
-
-@item 
-“The modulus and size of Test_and_Set_Flag.  See C.6.3(8).”
-@end itemize
-
-The modulus is 2**8. The size is 8.
-
-
-@itemize *
-
-@item 
-“The value used to represent the set value for Atomic_Test_and_Set.
-See C.6.3(10).”
-@end itemize
-
-The value is 1.
-
-
-@itemize *
-
-@item 
-“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 @code{Var}
-has a task type, the image for this task will have the form @code{Var_@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., @code{Group(5)_@var{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
-designates this task.
-
-If a task is created by an allocator, its image depends on the context. If the
-allocator is part of an object declaration, the rules described above are used
-to construct its image, and this image is not affected by subsequent
-assignments. If the allocator appears within an expression, the image
-includes only the name of the task type.
-
-If the configuration pragma Discard_Names is present, or if the restriction
-No_Implicit_Heap_Allocation is in effect,  the image reduces to
-the numeric suffix, that is to say the hexadecimal representation of the
-virtual address of the control block of the task.
-
-
-@itemize *
-
-@item 
-“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 @code{Current_Task} is undefined.
-
-
-@itemize *
-
-@item 
-“Granularity of locking for Task_Attributes.  See C.7.2(16).”
-@end itemize
-
-No locking is needed if the formal type Attribute has the size and
-alignment of either Integer or System.Address and the bit representation
-of Initial_Value is all zeroes. Otherwise, locking is performed.
-
-
-@itemize *
-
-@item 
-“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 execution resources.  See D.1(15).”
-@end itemize
-
-There are no implementation-defined execution resources.
-
-
-@itemize *
-
-@item 
-“Whether, on a multiprocessor, a task that is waiting for
-access to a protected object keeps its processor busy.  See D.2.1(3).”
-@end itemize
-
-On a multi-processor, a task that is waiting for access to a protected
-object does not keep its processor busy.
-
-
-@itemize *
-
-@item 
-“The affect of implementation defined execution resources
-on task dispatching.  See D.2.1(9).”
-@end itemize
-
-Tasks map to threads in the threads package used by GNAT.  Where possible
-and appropriate, these threads correspond to native threads of the
-underlying operating system.
-
-
-@itemize *
-
-@item 
-“Implementation-defined task dispatching policies.  See D.2.2(3).”
-@end itemize
-
-There are no implementation-defined task dispatching policies.
-
-
-@itemize *
-
-@item 
-“The value of Default_Quantum in Dispatching.Round_Robin.  See D.2.5(4).”
-@end itemize
-
-The value is 10 milliseconds.
-
-
-@itemize *
-
-@item 
-“Implementation-defined `policy_identifiers' allowed
-in a pragma @code{Locking_Policy}.  See D.3(4).”
-@end itemize
-
-The two implementation defined policies permitted in GNAT are
-@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
-@code{Concurrent_Readers_Locking} policy, locking is implemented with a
-read/write lock allowing multiple protected object functions to enter
-concurrently.
-
-
-@itemize *
-
-@item 
-“Default ceiling priorities.  See D.3(10).”
-@end itemize
-
-The ceiling priority of protected objects of the type
-@code{System.Interrupt_Priority'Last} as described in the Ada
-Reference Manual D.3(10),
-
-
-@itemize *
-
-@item 
-“The ceiling of any protected object used internally by
-the implementation.  See D.3(16).”
-@end itemize
-
-The ceiling priority of internal protected objects is
-@code{System.Priority'Last}.
-
-
-@itemize *
-
-@item 
-“Implementation-defined queuing policies.  See D.4(1).”
-@end itemize
-
-There are no implementation-defined queuing policies.
-
-
-@itemize *
-
-@item 
-“Implementation-defined admission policies.  See D.4.1(1).”
-@end itemize
-
-There are no implementation-defined admission policies.
-
-
-@itemize *
-
-@item 
-“Any operations that implicitly require heap storage
-allocation.  See D.7(8).”
-@end itemize
-
-The only operation that implicitly requires heap storage allocation is
-task creation.
-
-
-@itemize *
-
-@item 
-“When restriction No_Dynamic_CPU_Assignment applies to a partition, the
-processor on which a task with a CPU value of a Not_A_Specific_CPU will
-execute.  See D.7(10).”
-@end itemize
-
-Unknown.
-
-
-@itemize *
-
-@item 
-“When restriction No_Task_Termination applies to a partition, what happens
-when a task terminates.  See D.7(15.1).”
-@end itemize
-
-Execution is erroneous in that case.
-
-
-@itemize *
-
-@item 
-“The behavior when restriction Max_Storage_At_Blocking is violated.
-See D.7(17).”
-@end itemize
-
-Execution is erroneous in that case.
-
-
-@itemize *
-
-@item 
-“The behavior when restriction Max_Asynchronous_Select_Nesting is violated.
-See D.7(18).”
-@end itemize
-
-Execution is erroneous in that case.
-
-
-@itemize *
-
-@item 
-“The behavior when restriction Max_Tasks is violated.  See D.7(19).”
-@end itemize
-
-Execution is erroneous in that case.
-
-
-@itemize *
-
-@item 
-“Whether the use of pragma Restrictions results in a reduction in program
-code or data size or execution time.  See D.7(20).”
-
-Yes it can, but the precise circumstances and properties of such reductions
-are difficult to characterize.
-
-@item 
-“The value of Barrier_Limit’Last in Synchronous_Barriers.  See D.10.1(4).”
-@end itemize
-
-Synchronous_Barriers.Barrier_Limit’Last is Integer’Last .
-
-
-@itemize *
-
-@item 
-“When an aborted task that is waiting on a Synchronous_Barrier is aborted.
-See D.10.1(13).”
-@end itemize
-
-Difficult to characterize.
-
-
-@itemize *
-
-@item 
-“The value of Min_Handler_Ceiling in Execution_Time.Group_Budgets.
-See D.14.2(7).”
-@end itemize
-
-See source file @code{a-etgrbu.ads}.
-
-
-@itemize *
-
-@item 
-“The value of CPU_Range’Last in System.Multiprocessors.  See D.16(4).”
-@end itemize
-
-See source file @code{s-multip.ads}.
-
-
-@itemize *
-
-@item 
-“The processor on which the environment task executes in the absence
-of a value for the aspect CPU.  See D.16(13).”
-@end itemize
-
-Unknown.
-
-
-@itemize *
-
-@item 
-“The means for creating and executing distributed
-programs.  See E(5).”
-@end itemize
-
-The GLADE package provides a utility GNATDIST for creating and executing
-distributed programs. See the GLADE reference manual for further details.
-
-
-@itemize *
-
-@item 
-“Any events that can result in a partition becoming
-inaccessible.  See E.1(7).”
-@end itemize
-
-See the GLADE reference manual for full details on such events.
-
-
-@itemize *
-
-@item 
-“The scheduling policies, treatment of priorities, and management of
-shared resources between partitions in certain cases.  See E.1(11).”
-@end itemize
-
-See the GLADE reference manual for full details on these aspects of
-multi-partition execution.
-
-
-@itemize *
-
-@item 
-“Whether the execution of the remote subprogram is
-immediately aborted as a result of cancellation.  See E.4(13).”
-@end itemize
-
-See the GLADE reference manual for details on the effect of abort in
-a distributed application.
-
-
-@itemize *
-
-@item 
-“The range of type System.RPC.Partition_Id.  See E.5(14).”
-@end itemize
-
-System.RPC.Partition_ID’Last is Integer’Last. See source file @code{s-rpc.ads}.
-
-
-@itemize *
-
-@item 
-“Implementation-defined interfaces in the PCS.  See E.5(26).”
-@end itemize
-
-See the GLADE reference manual for a full description of all
-implementation defined interfaces.
-
-
-@itemize *
-
-@item 
-“The values of named numbers in the package
-@code{Decimal}.  See F.2(7).”
-@end itemize
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
-@headitem
-
-Named Number
-
-@tab
-
-Value
-
-@item
-
-`Max_Scale'
-
-@tab
-
-+18
-
-@item
-
-`Min_Scale'
-
-@tab
-
--18
-
-@item
-
-`Min_Delta'
-
-@tab
-
-1.0E-18
-
-@item
-
-`Max_Delta'
-
-@tab
-
-1.0E+18
-
-@item
-
-`Max_Decimal_Digits'
-
-@tab
-
-18
-
-@end multitable
-
-
-
-@itemize *
-
-@item 
-“The value of @code{Max_Picture_Length} in the package
-@code{Text_IO.Editing}.  See F.3.3(16).”
-
-64
-
-@item 
-“The value of @code{Max_Picture_Length} in the package
-@code{Wide_Text_IO.Editing}.  See F.3.4(5).”
-
-64
-
-@item 
-“The accuracy actually achieved by the complex elementary
-functions and by other complex arithmetic operations.  See G.1(1).”
-@end itemize
-
-Standard library functions are used for the complex arithmetic
-operations.  Only fast math mode is currently supported.
-
-
-@itemize *
-
-@item 
-“The sign of a zero result (or a component thereof) from
-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
-implementation advice.
-
-
-@itemize *
-
-@item 
-“The sign of a zero result (or a component thereof) from
-any operator or function in
-@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
-implementation advice.
-
-
-@itemize *
-
-@item 
-“Whether the strict mode or the relaxed mode is the
-default.  See G.2(2).”
-@end itemize
-
-The strict mode is the default.  There is no separate relaxed mode.  GNAT
-provides a highly efficient implementation of strict mode.
-
-
-@itemize *
-
-@item 
-“The result interval in certain cases of fixed-to-float
-conversion.  See G.2.1(10).”
-@end itemize
-
-For cases where the result interval is implementation dependent, the
-accuracy is that provided by performing all operations in 64-bit IEEE
-floating-point format.
-
-
-@itemize *
-
-@item 
-“The result of a floating point arithmetic operation in
-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
-floating-point standard.
-Note that on machines that are not fully compliant with the IEEE
-floating-point standard, such as Alpha, the `-mieee' compiler flag
-must be used for achieving IEEE conforming behavior (although at the cost
-of a significant performance penalty), so infinite and NaN values are
-properly generated.
-
-
-@itemize *
-
-@item 
-“The result interval for division (or exponentiation by a
-negative exponent), when the floating point hardware implements division
-as multiplication by a reciprocal.  See G.2.1(16).”
-@end itemize
-
-Not relevant, division is IEEE exact.
-
-
-@itemize *
-
-@item 
-“The definition of close result set, which determines the accuracy of
-certain fixed point multiplications and divisions.  See G.2.3(5).”
-@end itemize
-
-Operations in the close result set are performed using IEEE long format
-floating-point arithmetic.  The input operands are converted to
-floating-point, the operation is done in floating-point, and the result
-is converted to the target type.
-
-
-@itemize *
-
-@item 
-“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).”
-@end itemize
-
-The result is only defined to be in the perfect result set if the result
-can be computed by a single scaling operation involving a scale factor
-representable in 64 bits.
-
-
-@itemize *
-
-@item 
-“The result of a fixed point arithmetic operation in
-overflow situations, when the @code{Machine_Overflows} attribute of the
-result type is @code{False}.  See G.2.3(27).”
-@end itemize
-
-Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
-types.
-
-
-@itemize *
-
-@item 
-“The result of an elementary function reference in
-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.
-
-
-@itemize *
-
-@item 
-“The value of the angle threshold, within which certain
-elementary functions, complex arithmetic operations, and complex
-elementary functions yield results conforming to a maximum relative
-error bound.  See G.2.4(10).”
-@end itemize
-
-Information on this subject is not yet available.
-
-
-@itemize *
-
-@item 
-“The accuracy of certain elementary functions for
-parameters beyond the angle threshold.  See G.2.4(10).”
-@end itemize
-
-Information on this subject is not yet available.
-
-
-@itemize *
-
-@item 
-“The result of a complex arithmetic operation or complex
-elementary function reference in overflow situations, when the
-@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.
-
-
-@itemize *
-
-@item 
-“The accuracy of certain complex arithmetic operations and
-certain complex elementary functions for parameters (or components
-thereof) beyond the angle threshold.  See G.2.6(8).”
-@end itemize
-
-Information on those subjects is not yet available.
-
-
-@itemize *
-
-@item 
-“The accuracy requirements for the subprograms Solve, Inverse,
-Determinant, Eigenvalues and Eigensystem for type Real_Matrix.
-See G.3.1(81).”
-@end itemize
-
-Information on those subjects is not yet available.
-
-
-@itemize *
-
-@item 
-“The accuracy requirements for the subprograms Solve, Inverse,
-Determinant, Eigenvalues and Eigensystem for type Complex_Matrix.
-See G.3.2(149).”
-@end itemize
-
-Information on those subjects is not yet available.
-
-
-@itemize *
-
-@item 
-“The consequences of violating No_Hidden_Indirect_Globals.  See H.4(23.9).”
-@end itemize
-
-Execution is erroneous in that case.
-
-@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top
-@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{25d}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{25e}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}
-@chapter Intrinsic Subprograms
-
-
-@geindex Intrinsic Subprograms
-
-GNAT allows a user application program to write the declaration:
-
-@example
-pragma Import (Intrinsic, name);
-@end example
-
-providing that the name corresponds to one of the implemented intrinsic
-subprograms in GNAT, and that the parameter profile of the referenced
-subprogram meets the requirements.  This chapter describes the set of
-implemented intrinsic subprograms, and the requirements on parameter profiles.
-Note that no body is supplied; as with other uses of pragma Import, the
-body is supplied elsewhere (in this case by the compiler itself).  Note
-that any use of this feature is potentially non-portable, since the
-Ada standard does not require Ada compilers to implement this feature.
-
-@menu
-* Intrinsic Operators:: 
-* Compilation_ISO_Date:: 
-* Compilation_Date:: 
-* Compilation_Time:: 
-* Enclosing_Entity:: 
-* Exception_Information:: 
-* Exception_Message:: 
-* Exception_Name:: 
-* File:: 
-* Line:: 
-* Shifts and Rotates:: 
-* Source_Location:: 
-
-@end menu
-
-@node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{25f}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{260}
-@section Intrinsic Operators
-
-
-@geindex Intrinsic operator
-
-All the predefined numeric operators in package Standard
-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 @code{"**"} must have a root type of
-@code{Standard.Integer'Base}.
-You can use an intrinsic operator declaration as in the following example:
-
-@example
-type Int1 is new Integer;
-type Int2 is new Integer;
-
-function "+" (X1 : Int1; X2 : Int2) return Int1;
-function "+" (X1 : Int1; X2 : Int2) return Int2;
-pragma Import (Intrinsic, "+");
-@end example
-
-This declaration would permit ‘mixed mode’ arithmetic on items
-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_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{261}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{262}
-@section Compilation_ISO_Date
-
-
-@geindex Compilation_ISO_Date
-
-This intrinsic subprogram is used in the implementation 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
-@code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of
-the current compilation (in local time format YYYY-MM-DD).
-
-@node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{263}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{264}
-@section Compilation_Date
-
-
-@geindex Compilation_Date
-
-Same as Compilation_ISO_Date, except the string is in the form
-MMM DD YYYY.
-
-@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{265}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{266}
-@section Compilation_Time
-
-
-@geindex Compilation_Time
-
-This intrinsic subprogram is used in the implementation 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
-@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 enclosing-entity}@anchor{267}@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{268}
-@section Enclosing_Entity
-
-
-@geindex Enclosing_Entity
-
-This intrinsic subprogram is used in the implementation 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
-@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 exception-information}@anchor{269}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{26a}
-@section Exception_Information
-
-
-@geindex Exception_Information'
-
-This intrinsic subprogram is used in the implementation of the
-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
-@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{26b}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{26c}
-@section Exception_Message
-
-
-@geindex Exception_Message
-
-This intrinsic subprogram is used in the implementation of the
-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
-@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{26d}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{26e}
-@section Exception_Name
-
-
-@geindex Exception_Name
-
-This intrinsic subprogram is used in the implementation of the
-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
-@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{26f}@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{270}
-@section File
-
-
-@geindex File
-
-This intrinsic subprogram is used in the implementation 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
-@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 id11}@anchor{271}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{272}
-@section Line
-
-
-@geindex Line
-
-This intrinsic subprogram is used in the implementation 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
-@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 id12}@anchor{273}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{274}
-@section Shifts and Rotates
-
-
-@geindex Shift_Left
-
-@geindex Shift_Right
-
-@geindex Shift_Right_Arithmetic
-
-@geindex Rotate_Left
-
-@geindex Rotate_Right
-
-In standard Ada, the shift and rotate functions are available only
-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:
-
-@example
-function Shift_Left
-  (Value  : T;
-   Amount : Natural) return T
-with Import, Convention => Intrinsic;
-@end example
-
-The function name must be one of
-Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or
-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 @code{Value}.
-The shift amount must be Natural.
-The formal parameter names can be anything.
-
-A more convenient way of providing these shift operators is to use the
-Provide_Shift_Operators pragma, which provides the function declarations and
-corresponding pragma Import’s for all five shift functions. For signed types
-the semantics of these operators is to interpret the bitwise result of the
-corresponding operator for modular type. In particular, shifting a negative
-number may change its sign bit to positive.
-
-@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{275}@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{276}
-@section Source_Location
-
-
-@geindex Source_Location
-
-This intrinsic subprogram is used in the implementation 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
-@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 doc}@anchor{277}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{278}@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}
-@chapter Representation Clauses and Pragmas
-
-
-@geindex Representation Clauses
-
-@geindex Representation Clause
-
-@geindex Representation Pragma
-
-@geindex Pragma
-@geindex representation
-
-This section describes the representation clauses accepted by GNAT, and
-their effect on the representation of corresponding data objects.
-
-GNAT fully implements Annex C (Systems Programming).  This means that all
-the implementation advice sections in chapter 13 are fully implemented.
-However, these sections only require a minimal level of support for
-representation clauses.  GNAT provides much more extensive capabilities,
-and this section describes the additional capabilities provided.
-
-@menu
-* Alignment Clauses:: 
-* Size Clauses:: 
-* Storage_Size Clauses:: 
-* Size of Variant Record Objects:: 
-* Biased Representation:: 
-* Value_Size and Object_Size Clauses:: 
-* Component_Size Clauses:: 
-* Bit_Order Clauses:: 
-* Effect of Bit_Order on Byte Ordering:: 
-* Pragma Pack for Arrays:: 
-* Pragma Pack for Records:: 
-* Record Representation Clauses:: 
-* Handling of Records with Holes:: 
-* Enumeration Clauses:: 
-* Address Clauses:: 
-* Use of Address Clauses for Memory-Mapped I/O:: 
-* Effect of Convention on Representation:: 
-* Conventions and Anonymous Access Types:: 
-* Determining the Representations chosen by GNAT:: 
-
-@end menu
-
-@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{279}@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{27a}
-@section Alignment Clauses
-
-
-@geindex Alignment Clause
-
-GNAT requires that all alignment clauses specify 0 or a power of 2, and
-all default alignments are always a power of 2. Specifying 0 is the
-same as specifying 1.
-
-The default alignment values are as follows:
-
-
-@itemize *
-
-@item 
-`Elementary Types'.
-
-For elementary types, the alignment is the minimum of the actual size of
-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
-@code{Standard'Maximum_Alignment}; see @ref{18c,,Attribute Maximum_Alignment}.)
-
-@geindex Maximum_Alignment attribute
-
-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 @code{Long_Float} will be maximally
-aligned.
-
-@item 
-`Arrays'.
-
-For arrays, the alignment is equal to the alignment of the component type
-for the normal case where no packing or component size is given.  If the
-array is packed, and the packing is effective (see separate section on
-packed arrays), then the alignment will be either 4, 2, or 1 for long packed
-arrays or arrays whose length is not known at compile time, depending on
-whether the component size is divisible by 4, 2, or is odd.  For short packed
-arrays, which are handled internally as modular types, the alignment
-will be as described for elementary types, e.g. a packed array of length
-31 bits will have an object size of four bytes, and an alignment of 4.
-
-@item 
-`Records'.
-
-For the normal unpacked 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 @code{Pack}
-is used and all components are packable (see separate section on pragma
-@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:
-
-
-@itemize *
-
-@item 
-the size of the record is given explicitly, or a
-full record representation clause is given, and
-
-@item 
-the size of the record is 2, 4, or 8 bytes.
-@end itemize
-
-In this case, an alignment is chosen to match the
-size of the record. For example, if we have:
-
-@example
-type Small is record
-   A, B : Character;
-end record;
-for Small'Size use 16;
-@end example
-
-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 @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 @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
-
-@example
-type V is record
-   A : Integer;
-end record;
-
-for V'alignment use 1;
-@end example
-
-@geindex Alignment
-@geindex default
-
-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.
-
-@geindex Alignment
-@geindex subtypes
-
-Note that according to the Ada standard, an alignment clause applies only
-to the first named subtype. If additional subtypes are declared, then the
-compiler is allowed to choose any alignment it likes, and there is no way
-to control this choice. Consider:
-
-@example
-type R is range 1 .. 10_000;
-for R'Alignment use 1;
-subtype RS is R range 1 .. 1000;
-@end example
-
-The alignment clause specifies an alignment of 1 for the first named subtype
-@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 @code{RS} being 1. But this
-assumption is non-portable, and other compilers may choose different
-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{27b}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{27c}
-@section Size Clauses
-
-
-@geindex Size Clause
-
-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
-@code{T'Object_Size})
-is a multiple of @code{T'Alignment * Storage_Unit}.
-
-For example:
-
-@example
-type Smallint is range 1 .. 6;
-
-type Rec is record
-   Y1 : integer;
-   Y2 : boolean;
-end record;
-@end example
-
-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
-(@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 @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
-in accordance with the specific Implementation Advice in RM 13.3(43):
-
-@quotation
-
-“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
-@code{Alignment} (if the @code{Alignment} is nonzero).”
-@end quotation
-
-An explicit size clause may be used to override the default size by
-increasing it.  For example, if we have:
-
-@example
-type My_Boolean is new Boolean;
-for My_Boolean'Size use 32;
-@end example
-
-then values of this type will always be 32-bit long.  In the case of discrete
-types, the size can be increased up to 64 bits on 32-bit targets and 128 bits
-on 64-bit targets, with the effect that the entire specified field is used to
-hold the value, sign- or zero-extended as appropriate.  If more than 64 bits
-or 128 bits resp. is specified, then padding space is allocated after the
-value, and a warning is issued that there are unused bits.
-
-Similarly the size of records and arrays may be increased, and the effect
-is to add padding bits after the value.  This also causes a warning message
-to be generated.
-
-The largest Size value permitted in GNAT is 2**31-1.  Since this is a
-Size in bits, this corresponds to an object of size 256 megabytes (minus
-one).  This limitation is true on all targets.  The reason for this
-limitation is that it improves the quality of the code in many cases
-if it is known that a Size value can be accommodated in an object of
-type Integer.
-
-@node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{27d}@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{27e}
-@section Storage_Size Clauses
-
-
-@geindex Storage_Size Clause
-
-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 @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:
-
-@example
-pragma Storage_Size (Default_Stack_Size);
-@end example
-
-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 `-d' binder switch to modify the default stack
-size.
-
-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 @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 @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
-@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:
-
-@example
-procedure p is
-   type R is array (Natural) of Character;
-   type P is access all R;
-   for P'Storage_Size use 0;
-   --  Above access type intended only for interfacing purposes
-
-   y : P;
-
-   procedure g (m : P);
-   pragma Import (C, g);
-
-   --  ...
-
-begin
-   --  ...
-   y := new R;
-end;
-@end example
-
-As indicated in this example, these dummy storage pools are often useful in
-connection with interfacing where no object will ever be allocated.  If you
-compile the above example, you get the warning:
-
-@example
-p.adb:16:09: warning: allocation from empty storage pool
-p.adb:16:09: warning: Storage_Error will be raised at run time
-@end example
-
-Of course in practice, there will not be any explicit allocators in the
-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{27f}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{280}
-@section Size of Variant Record Objects
-
-
-@geindex Size
-@geindex variant record objects
-
-@geindex Variant record objects
-@geindex size
-
-In the case of variant record objects, there is a question whether Size gives
-information about a particular variant, or the maximum size required
-for any variant.  Consider the following program
-
-@example
-with Text_IO; use Text_IO;
-procedure q is
-   type R1 (A : Boolean := False) is record
-     case A is
-       when True  => X : Character;
-       when False => null;
-     end case;
-   end record;
-
-   V1 : R1 (False);
-   V2 : R1;
-
-begin
-   Put_Line (Integer'Image (V1'Size));
-   Put_Line (Integer'Image (V2'Size));
-end q;
-@end example
-
-Here we are dealing with a variant record, where the True variant
-requires 16 bits, and the False variant requires 8 bits.
-In the above example, both V1 and V2 contain the False variant,
-which is only 8 bits long.  However, the result of running the
-program is:
-
-@example
-8
-16
-@end example
-
-The reason for the difference here is that the discriminant value of
-V1 is fixed, and will always be False.  It is not possible to assign
-a True variant value to V1, therefore 8 bits is sufficient.  On the
-other hand, in the case of V2, the initial discriminant value is
-False (from the default), but it is possible to assign a True
-variant value to V2, therefore 16 bits must be allocated for V2
-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 @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
-be made here, but the GNAT behavior seems most consistent with the
-language in the RM.
-
-In some cases, it may be desirable to obtain the size of the current
-variant, rather than the size of the largest variant.  This can be
-achieved in GNAT by making use of the fact that in the case of a
-subprogram parameter, GNAT does indeed return the size of the current
-variant (because a subprogram has no way of knowing how much space
-is actually allocated for the actual).
-
-Consider the following modified version of the above program:
-
-@example
-with Text_IO; use Text_IO;
-procedure q is
-   type R1 (A : Boolean := False) is record
-     case A is
-       when True  => X : Character;
-       when False => null;
-     end case;
-   end record;
-
-   V2 : R1;
-
-   function Size (V : R1) return Integer is
-   begin
-      return V'Size;
-   end Size;
-
-begin
-   Put_Line (Integer'Image (V2'Size));
-   Put_Line (Integer'Image (Size (V2)));
-   V2 := (True, 'x');
-   Put_Line (Integer'Image (V2'Size));
-   Put_Line (Integer'Image (Size (V2)));
-end q;
-@end example
-
-The output from this program is
-
-@example
-16
-8
-16
-16
-@end example
-
-Here we see that while the @code{'Size} attribute always returns
-the maximum size, regardless of the current variant value, the
-@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 biased-representation}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{282}
-@section Biased Representation
-
-
-@geindex Size for biased representation
-
-@geindex Biased representation
-
-In the case of scalars with a range starting at other than zero, it is
-possible in some cases to specify a size smaller than the default minimum
-value, and in such cases, GNAT uses an unsigned biased representation,
-in which zero is used to represent the lower bound, and successive values
-represent successive values of the type.
-
-For example, suppose we have the declaration:
-
-@example
-type Small is range -7 .. -4;
-for Small'Size use 2;
-@end example
-
-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:
-
-@example
--7 is represented as 2#00#
--6 is represented as 2#01#
--5 is represented as 2#10#
--4 is represented as 2#11#
-@end example
-
-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{283}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{284}
-@section Value_Size and Object_Size Clauses
-
-
-@geindex Value_Size
-
-@geindex Object_Size
-
-@geindex Size
-@geindex of objects
-
-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, @code{Natural'Size} was 32.
-However, in Ada 95 and Ada 2005,
-@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:
-
-@example
-type Rec is record
-   A : Natural;
-   B : Natural;
-end record;
-
-for Rec use record
-   A at 0 range 0 .. Natural'Size - 1;
-   B at 0 range Natural'Size .. 2 * Natural'Size - 1;
-end record;
-@end example
-
-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, @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 @code{Object_Size} is used for determining the default size of
-objects and components.  This size value can be referred to using the
-@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 @code{Object_Size} for
-discrete types are as follows:
-
-
-@itemize *
-
-@item 
-The @code{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.
-
-@item 
-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 @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 @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 @code{Value_Size} values differ generate a warning, and are potentially
-target dependent).
-
-The default rules for the value of @code{Value_Size} are as follows:
-
-
-@itemize *
-
-@item 
-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 @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 @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 @code{Size} corresponds to the
-@code{Value_Size} attribute.
-
-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
-@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 @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 @code{Value_Size} of any other static subtypes is not affected.
-
-@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 @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 @code{Object_Size} attribute.
-
-To get a feel for the difference, consider the following examples (note
-that in each case the base is @code{Short_Short_Integer} with a size of 8):
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} 
-@headitem
-
-Type or subtype declaration
-
-@tab
-
-Object_Size
-
-@tab
-
-Value_Size
-
-@item
-
-@code{type x1 is range 0 .. 5;}
-
-@tab
-
-8
-
-@tab
-
-3
-
-@item
-
-@code{type x2 is range 0 .. 5;}
-@code{for x2'size use 12;}
-
-@tab
-
-16
-
-@tab
-
-12
-
-@item
-
-@code{subtype x3 is x2 range 0 .. 3;}
-
-@tab
-
-16
-
-@tab
-
-2
-
-@item
-
-@code{subtype x4 is x2'base range 0 .. 10;}
-
-@tab
-
-8
-
-@tab
-
-4
-
-@item
-
-@code{dynamic : x2'Base range -64 .. +63;}
-
-@tab
-
-@tab
-
-@item
-
-@code{subtype x5 is x2 range 0 .. dynamic;}
-
-@tab
-
-16
-
-@tab
-
-3*
-
-@item
-
-@code{subtype x6 is x2'base range 0 .. dynamic;}
-
-@tab
-
-8
-
-@tab
-
-7*
-
-@end multitable
-
-
-Note: the entries marked ‘*’ are not actually specified by the Ada
-Reference Manual, which has nothing to say about size in the dynamic
-case. What GNAT does is to allocate sufficient bits to accommodate any
-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 @code{Size} be used.
-The following is a list
-of the occasions on which the RM @code{Size} must be used:
-
-
-@itemize *
-
-@item 
-Component size for packed arrays or records
-
-@item 
-Value of the attribute @code{Size} for a type
-
-@item 
-Warning about sizes not matching for unchecked conversion
-@end itemize
-
-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
-@code{Value_Size} can be smaller. Consider:
-
-@example
-type R is record
-  X : Integer;
-  Y : Character;
-end record;
-@end example
-
-On a typical 32-bit architecture, the X component will occupy four bytes
-and the Y component will occupy one byte, for a total of 5 bytes. As a
-result @code{R'Value_Size} will be 40 (bits) since this is the minimum size
-required to store a value of this type. For example, it is permissible
-to have a component of type R in an array whose component size is
-specified to be 40 bits.
-
-However, @code{R'Object_Size} will be 64 (bits). The difference is due to
-the alignment requirement for objects of the record type. The X
-component will require four-byte alignment because that is what type
-Integer requires, whereas the Y component, a Character, will only
-require 1-byte alignment. Since the alignment required for X is the
-greatest of all the components’ alignments, that is the alignment
-required for the enclosing record type, i.e., 4 bytes or 32 bits. As
-indicated above, the actual object size must be rounded up so that it is
-a multiple of the alignment value. Therefore, 40 bits rounded up to the
-next multiple of 32 yields 64 bits.
-
-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 @code{Value_Size} can be used to force biased representation
-for a particular subtype. Consider this example:
-
-@example
-type R is (A, B, C, D, E, F);
-subtype RAB is R range A .. B;
-subtype REF is R range E .. F;
-@end example
-
-By default, @code{RAB}
-has a size of 1 (sufficient to accommodate the representation
-of @code{A} and @code{B}, 0 and 1), and @code{REF}
-has a size of 3 (sufficient to accommodate the representation
-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 @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 @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 component-size-clauses}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{286}
-@section Component_Size Clauses
-
-
-@geindex Component_Size Clause
-
-Normally, the value specified in a component size clause must be consistent
-with the subtype of the array component with regard to size and alignment.
-In other words, the value specified must be at least equal to the size
-of this subtype, and must be a multiple of the alignment value.
-
-In addition, component size clauses are allowed which cause the array
-to be packed, by specifying a smaller value.  A first case is for
-component size values in the range 1 through 63 on 32-bit targets,
-and 1 through 127 on 64-bit targets.  The value specified may not
-be smaller than the Size of the subtype.  GNAT will accurately
-honor all packing requests in this range.  For example, if we have:
-
-@example
-type r is array (1 .. 8) of Natural;
-for r'Component_Size use 31;
-@end example
-
-then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
-Of course access to the components of such an array is considerably
-less efficient than if the natural component size of 32 is used.
-A second case is when the subtype of the component is a record type
-padded because of its default alignment.  For example, if we have:
-
-@example
-type r is record
-  i : Integer;
-  j : Integer;
-  b : Boolean;
-end record;
-
-type a is array (1 .. 8) of r;
-for a'Component_Size use 72;
-@end example
-
-then the resulting array has a length of 72 bytes, instead of 96 bytes
-if the alignment of the record (4) was obeyed.
-
-Note that there is no point in giving both a component size clause
-and a pragma Pack for the same array type. if such duplicate
-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{287}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{288}
-@section Bit_Order Clauses
-
-
-@geindex Bit_Order Clause
-
-@geindex bit ordering
-
-@geindex ordering
-@geindex of bits
-
-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
-setting (that is the opposite of the default).
-
-In the case where the non-standard value is specified, the effect is
-to renumber bits within each byte, but the ordering of bytes is not
-affected.  There are certain
-restrictions placed on component clauses as follows:
-
-
-@itemize *
-
-@item 
-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 @code{Low_Order_First}
-being the default, then the following two declarations have exactly
-the same effect:
-
-@example
-type R1 is record
-   A : Boolean;
-   B : Integer range 1 .. 120;
-end record;
-
-for R1 use record
-   A at 0 range 0 .. 0;
-   B at 0 range 1 .. 7;
-end record;
-
-type R2 is record
-   A : Boolean;
-   B : Integer range 1 .. 120;
-end record;
-
-for R2'Bit_Order use High_Order_First;
-
-for R2 use record
-   A at 0 range 7 .. 7;
-   B at 0 range 0 .. 6;
-end record;
-@end example
-
-The useful application here is to write the second declaration with the
-@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 
-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 @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:
-
-@example
-type R2 is record
-   A : Integer;
-end record;
-
-for R2'Bit_Order use High_Order_First;
-
-for R2 use record
-   A at 0 range 0 .. 31;
-end record;
-@end example
-
-This declaration will result in a little-endian integer on a
-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 @code{Bit_Order}.
-
-@item 
-Components that are positioned across byte boundaries.
-
-but do not occupy an integral number of bytes.  Given that bytes are not
-reordered, such fields would occupy a non-contiguous sequence of bits
-in memory, requiring non-trivial code to reassemble.  They are for this
-reason not permitted, and any component clause specifying such a layout
-will be flagged as illegal by GNAT.
-@end itemize
-
-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 @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 effect-of-bit-order-on-byte-ordering}@anchor{289}@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{28a}
-@section Effect of Bit_Order on Byte Ordering
-
-
-@geindex byte ordering
-
-@geindex ordering
-@geindex of bytes
-
-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 @code{Bit_Order}.  The effect of a
-non-standard bit order is described in section 13.5.3 of the Ada
-Reference Manual:
-
-@quotation
-
-“2   A bit ordering is a method of interpreting the meaning of
-the storage place attributes.”
-@end quotation
-
-To understand the precise definition of storage place attributes in
-this context, we visit section 13.5.1 of the manual:
-
-@quotation
-
-“13   A record_representation_clause (without the mod_clause)
-specifies the layout.  The storage place attributes (see 13.5.2)
-are taken from the values of the position, first_bit, and last_bit
-expressions after normalizing those values so that first_bit is
-less than Storage_Unit.”
-@end quotation
-
-The critical point here is that storage places are taken from
-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:
-
-@quotation
-
-“2   A bit ordering is a method of interpreting the meaning of
-the storage place attributes.  High_Order_First (known in the
-vernacular as ‘big endian’) means that the first bit of a
-storage element (bit 0) is the most significant bit (interpreting
-the sequence of bits that represent a component as an unsigned
-integer value).  Low_Order_First (known in the vernacular as
-‘little endian’) means the opposite: the first bit is the
-least significant.”
-@end quotation
-
-Note that the numbering is with respect to the bits of a storage
-unit.  In other words, the specification affects only the numbering
-of bits within a single storage unit.
-
-We can make the effect clearer by giving an example.
-
-Suppose that we have an external device which presents two bytes, the first
-byte presented, which is the first (low addressed byte) of the two byte
-record is called Master, and the second byte is called Slave.
-
-The left most (most significant) bit is called Control for each byte, and
-the remaining 7 bits are called V1, V2, … V7, where V7 is the rightmost
-(least significant) bit.
-
-On a big-endian machine, we can write the following representation clause
-
-@example
-type Data is record
-   Master_Control : Bit;
-   Master_V1      : Bit;
-   Master_V2      : Bit;
-   Master_V3      : Bit;
-   Master_V4      : Bit;
-   Master_V5      : Bit;
-   Master_V6      : Bit;
-   Master_V7      : Bit;
-   Slave_Control  : Bit;
-   Slave_V1       : Bit;
-   Slave_V2       : Bit;
-   Slave_V3       : Bit;
-   Slave_V4       : Bit;
-   Slave_V5       : Bit;
-   Slave_V6       : Bit;
-   Slave_V7       : Bit;
-end record;
-
-for Data use record
-   Master_Control at 0 range 0 .. 0;
-   Master_V1      at 0 range 1 .. 1;
-   Master_V2      at 0 range 2 .. 2;
-   Master_V3      at 0 range 3 .. 3;
-   Master_V4      at 0 range 4 .. 4;
-   Master_V5      at 0 range 5 .. 5;
-   Master_V6      at 0 range 6 .. 6;
-   Master_V7      at 0 range 7 .. 7;
-   Slave_Control  at 1 range 0 .. 0;
-   Slave_V1       at 1 range 1 .. 1;
-   Slave_V2       at 1 range 2 .. 2;
-   Slave_V3       at 1 range 3 .. 3;
-   Slave_V4       at 1 range 4 .. 4;
-   Slave_V5       at 1 range 5 .. 5;
-   Slave_V6       at 1 range 6 .. 6;
-   Slave_V7       at 1 range 7 .. 7;
-end record;
-@end example
-
-Now if we move this to a little endian machine, then the bit ordering within
-the byte is backwards, so we have to rewrite the record rep clause as:
-
-@example
-for Data use record
-   Master_Control at 0 range 7 .. 7;
-   Master_V1      at 0 range 6 .. 6;
-   Master_V2      at 0 range 5 .. 5;
-   Master_V3      at 0 range 4 .. 4;
-   Master_V4      at 0 range 3 .. 3;
-   Master_V5      at 0 range 2 .. 2;
-   Master_V6      at 0 range 1 .. 1;
-   Master_V7      at 0 range 0 .. 0;
-   Slave_Control  at 1 range 7 .. 7;
-   Slave_V1       at 1 range 6 .. 6;
-   Slave_V2       at 1 range 5 .. 5;
-   Slave_V3       at 1 range 4 .. 4;
-   Slave_V4       at 1 range 3 .. 3;
-   Slave_V5       at 1 range 2 .. 2;
-   Slave_V6       at 1 range 1 .. 1;
-   Slave_V7       at 1 range 0 .. 0;
-end record;
-@end example
-
-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
-@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
-first record clause, together with the declaration
-
-@example
-for Data'Bit_Order use High_Order_First;
-@end example
-
-and the effect is what is desired, namely the layout is exactly the same,
-independent of whether the code is compiled on a big-endian or little-endian
-machine.
-
-The important point to understand is that byte ordering is not affected.
-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:
-
-@example
-for Data'Bit_Order use High_Order_First;
-for Data use record
-   Master_Control at 0 range  0 .. 0;
-   Master_V1      at 0 range  1 .. 1;
-   Master_V2      at 0 range  2 .. 2;
-   Master_V3      at 0 range  3 .. 3;
-   Master_V4      at 0 range  4 .. 4;
-   Master_V5      at 0 range  5 .. 5;
-   Master_V6      at 0 range  6 .. 6;
-   Master_V7      at 0 range  7 .. 7;
-   Slave_Control  at 0 range  8 .. 8;
-   Slave_V1       at 0 range  9 .. 9;
-   Slave_V2       at 0 range 10 .. 10;
-   Slave_V3       at 0 range 11 .. 11;
-   Slave_V4       at 0 range 12 .. 12;
-   Slave_V5       at 0 range 13 .. 13;
-   Slave_V6       at 0 range 14 .. 14;
-   Slave_V7       at 0 range 15 .. 15;
-end record;
-@end example
-
-This is exactly equivalent to saying (a repeat of the first example):
-
-@example
-for Data'Bit_Order use High_Order_First;
-for Data use record
-   Master_Control at 0 range 0 .. 0;
-   Master_V1      at 0 range 1 .. 1;
-   Master_V2      at 0 range 2 .. 2;
-   Master_V3      at 0 range 3 .. 3;
-   Master_V4      at 0 range 4 .. 4;
-   Master_V5      at 0 range 5 .. 5;
-   Master_V6      at 0 range 6 .. 6;
-   Master_V7      at 0 range 7 .. 7;
-   Slave_Control  at 1 range 0 .. 0;
-   Slave_V1       at 1 range 1 .. 1;
-   Slave_V2       at 1 range 2 .. 2;
-   Slave_V3       at 1 range 3 .. 3;
-   Slave_V4       at 1 range 4 .. 4;
-   Slave_V5       at 1 range 5 .. 5;
-   Slave_V6       at 1 range 6 .. 6;
-   Slave_V7       at 1 range 7 .. 7;
-end record;
-@end example
-
-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 @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 @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,
-not which byte they end up in.
-
-Consequently it never makes sense to specify a starting bit number
-greater than 7 (for a byte addressable field) if an attribute
-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.
-
-If you do need to control byte ordering then appropriate conditional
-values must be used.  If in our example, the slave byte came first on
-some machines we might write:
-
-@example
-Master_Byte_First constant Boolean := ...;
-
-Master_Byte : constant Natural :=
-                1 - Boolean'Pos (Master_Byte_First);
-Slave_Byte  : constant Natural :=
-                Boolean'Pos (Master_Byte_First);
-
-for Data'Bit_Order use High_Order_First;
-for Data use record
-   Master_Control at Master_Byte range 0 .. 0;
-   Master_V1      at Master_Byte range 1 .. 1;
-   Master_V2      at Master_Byte range 2 .. 2;
-   Master_V3      at Master_Byte range 3 .. 3;
-   Master_V4      at Master_Byte range 4 .. 4;
-   Master_V5      at Master_Byte range 5 .. 5;
-   Master_V6      at Master_Byte range 6 .. 6;
-   Master_V7      at Master_Byte range 7 .. 7;
-   Slave_Control  at Slave_Byte  range 0 .. 0;
-   Slave_V1       at Slave_Byte  range 1 .. 1;
-   Slave_V2       at Slave_Byte  range 2 .. 2;
-   Slave_V3       at Slave_Byte  range 3 .. 3;
-   Slave_V4       at Slave_Byte  range 4 .. 4;
-   Slave_V5       at Slave_Byte  range 5 .. 5;
-   Slave_V6       at Slave_Byte  range 6 .. 6;
-   Slave_V7       at Slave_Byte  range 7 .. 7;
-end record;
-@end example
-
-Now to switch between machines, all that is necessary is
-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 id11}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{28c}
-@section Pragma Pack for Arrays
-
-
-@geindex Pragma Pack (for arrays)
-
-Pragma @code{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:
-
-
-@itemize *
-
-@item 
-Any elementary type.
-
-@item 
-Any small packed array type with a static size.
-
-@item 
-Any small simple record type with a static size.
-@end itemize
-
-For all these cases, if the component subtype size is in the range
-1 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets,
-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
-units and the only effect of pragma Pack is to remove alignment gaps.
-
-For example if we have:
-
-@example
-type r is range 0 .. 17;
-
-type ar is array (1 .. 8) of r;
-pragma Pack (ar);
-@end example
-
-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 @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 @code{Pack} that it guesses
-might not be what is intended.  You can easily remove this warning by
-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
-known at compile time and is at most 64 bits on 32-bit targets, and at most
-128 bits on 64-bit targets, then internally the array is represented as a
-single modular type, of exactly the appropriate number of bits.  If the
-length is greater than 64 bits on 32-bit targets, and greater than 128
-bits on 64-bit targets, or is not known at compile time, then the packed
-array is represented as an array of bytes, and its length is always a
-multiple of 8 bits.
-
-Note that to represent a packed array as a modular type, the alignment must
-be suitable for the modular type involved. For example, on typical machines
-a 32-bit packed array will be represented by a 32-bit modular integer with
-an alignment of four bytes. If you explicitly override the default alignment
-with an alignment clause that is too small, the modular representation
-cannot be used. For example, consider the following set of declarations:
-
-@example
-type R is range 1 .. 3;
-type S is array (1 .. 31) of R;
-for S'Component_Size use 2;
-for S'Size use 62;
-for S'Alignment use 1;
-@end example
-
-If the alignment clause were not present, then a 62-bit modular
-representation would be chosen (typically with an alignment of 4 or 8
-bytes depending on the target). But the default alignment is overridden
-with the explicit alignment clause. This means that the modular
-representation cannot be used, and instead the array of bytes
-representation must be used, meaning that the length must be a multiple
-of 8. Thus the above set of declarations will result in a diagnostic
-rejecting the size clause and noting that the minimum size allowed is 64.
-
-@geindex Pragma Pack (for type Natural)
-
-@geindex Pragma Pack warning
-
-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 @code{Natural}. Consider:
-
-@example
-type Arr is array (1 .. 32) of Natural;
-pragma Pack (Arr);
-@end example
-
-In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
-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, @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
-want 31 bit packing in a case like this, you can set the component size
-explicitly:
-
-@example
-type Arr is array (1 .. 32) of Natural;
-for Arr'Component_Size use 31;
-@end example
-
-Here 31-bit packing is achieved as required, and no warning is generated,
-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 id12}@anchor{28d}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{28e}
-@section Pragma Pack for Records
-
-
-@geindex Pragma Pack (for records)
-
-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 `packable' components and
-`non-packable' components.
-Components of the following types are considered packable:
-
-
-@itemize *
-
-@item 
-Components of an elementary type are packable unless they are aliased,
-independent or atomic.
-
-@item 
-Small packed arrays, where the size is statically known, are represented
-internally as modular integers, and so they are also packable.
-
-@item 
-Small simple records, where the size is statically known, are also packable.
-@end itemize
-
-For all these cases, if the @code{'Size} value is in the range 1 through 64 on
-32-bit targets, and 1 through 128 on 64-bit targets, 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 @code{Pack} is to remove alignment gaps.
-
-For example, consider the record
-
-@example
-type Rb1 is array (1 .. 13) of Boolean;
-pragma Pack (Rb1);
-
-type Rb2 is array (1 .. 65) of Boolean;
-pragma Pack (Rb2);
-
-type AF is new Float with Atomic;
-
-type X2 is record
-   L1 : Boolean;
-   L2 : Duration;
-   L3 : AF;
-   L4 : Boolean;
-   L5 : Rb1;
-   L6 : Rb2;
-end record;
-pragma Pack (X2);
-@end example
-
-The representation for the record @code{X2} is as follows on 32-bit targets:
-
-@example
-for X2'Size use 224;
-for X2 use record
-   L1 at  0 range  0 .. 0;
-   L2 at  0 range  1 .. 64;
-   L3 at 12 range  0 .. 31;
-   L4 at 16 range  0 .. 0;
-   L5 at 16 range  1 .. 13;
-   L6 at 18 range  0 .. 71;
-end record;
-@end example
-
-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 @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 @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 on
-32-bit targets.  Thus 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{28f}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{290}
-@section Record Representation Clauses
-
-
-@geindex Record Representation Clause
-
-Record representation clauses may be given for all record types, including
-types obtained by record extension.  Component clauses are allowed for any
-static component.  The restrictions on component clauses depend on the type
-of the component.
-
-@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 @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.
-
-Packed arrays with a size up to and including 64 bits on 32-bit targets,
-and up to and including 128 bits on 64-bit targets, are represented
-internally using a modular type with the appropriate number of bits, and
-thus the same lack of restriction applies.  For example, if you declare:
-
-@example
-type R is array (1 .. 49) of Boolean;
-pragma Pack (R);
-for R'Size use 49;
-@end example
-
-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 on 32-bit targets,
-and longer than 128 bits on 64-bit targets, there are two cases. If the
-component size is a power of 2 (1,2,4,8,16,32,64 bits), including the
-important case of single bits or boolean values, then there are no
-limitations on placement of such components, and they may start and
-end at arbitrary bit boundaries.
-
-If the component size is not a power of 2 (e.g., 3 or 5), then an array
-of this type must always be placed on on a storage unit (byte) boundary
-and occupy an integral number of storage units (bytes). Any component
-clause that does not meet this requirement will be rejected.
-
-Any aliased component, or component of an aliased type, must have its
-normal alignment and size. A component clause that does not meet this
-requirement will be rejected.
-
-The tag field of a tagged type always occupies an address sized field at
-the start of the record.  No component clause may attempt to overlay this
-tag. When a tagged type appears as a component, the tag field must have
-proper alignment
-
-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'Object_Size} bits of the record.
-
-For all other component types, including non-bit-packed arrays,
-the component can be placed at an arbitrary bit boundary,
-so for example, the following is permitted:
-
-@example
-type R is array (1 .. 10) of Boolean;
-for R'Size use 80;
-
-type Q is record
-   G, H : Boolean;
-   L, M : R;
-end record;
-
-for Q use record
-   G at 0 range  0 ..   0;
-   H at 0 range  1 ..   1;
-   L at 0 range  2 ..  81;
-   R at 0 range 82 .. 161;
-end record;
-@end example
-
-@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{291}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{292}
-@section Handling of Records with Holes
-
-
-@geindex Handling of Records with Holes
-
-As a result of alignment considerations, records may contain “holes”
-or gaps which do not correspond to the data bits of any of the components.
-Record representation clauses can also result in holes in records.
-
-GNAT does not attempt to clear these holes, so in record objects,
-they should be considered to hold undefined rubbish. The generated
-equality routine just tests components so does not access these
-undefined bits, and assignment and copy operations may or may not
-preserve the contents of these holes (for assignments, the holes
-in the target will in practice contain either the bits that are
-present in the holes in the source, or the bits that were present
-in the target before the assignment).
-
-If it is necessary to ensure that holes in records have all zero
-bits, then record objects for which this initialization is desired
-should be explicitly set to all zero values using Unchecked_Conversion
-or address overlays. For example
-
-@example
-type HRec is record
-   C : Character;
-   I : Integer;
-end record;
-@end example
-
-On typical machines, integers need to be aligned on a four-byte
-boundary, resulting in three bytes of undefined rubbish following
-the 8-bit field for C. To ensure that the hole in a variable of
-type HRec is set to all zero bits,
-you could for example do:
-
-@example
-type Base is record
-   Dummy1, Dummy2 : Integer := 0;
-end record;
-
-BaseVar : Base;
-RealVar : Hrec;
-for RealVar'Address use BaseVar'Address;
-@end example
-
-Now the 8-bytes of the value of RealVar start out containing all zero
-bits. A safer approach is to just define dummy fields, avoiding the
-holes, as in:
-
-@example
-type HRec is record
-   C      : Character;
-   Dummy1 : Short_Short_Integer := 0;
-   Dummy2 : Short_Short_Integer := 0;
-   Dummy3 : Short_Short_Integer := 0;
-   I      : Integer;
-end record;
-@end example
-
-And to make absolutely sure that the intent of this is followed, you
-can use representation clauses:
-
-@example
-for Hrec use record
-   C      at 0 range 0 .. 7;
-   Dummy1 at 1 range 0 .. 7;
-   Dummy2 at 2 range 0 .. 7;
-   Dummy3 at 3 range 0 .. 7;
-   I      at 4 range 0 .. 31;
-end record;
-for Hrec'Size use 64;
-@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{293}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{294}
-@section Enumeration Clauses
-
-
-The only restriction on enumeration clauses is that the range of values
-must be representable.  For the signed case, if one or more of the
-representation values are negative, all values must be in the range:
-
-@example
-System.Min_Int .. System.Max_Int
-@end example
-
-For the unsigned case, where all values are nonnegative, the values must
-be in the range:
-
-@example
-0 .. System.Max_Binary_Modulus;
-@end example
-
-A `confirming' representation clause is one in which the values range
-from 0 in sequence, i.e., a clause that confirms the default representation
-for an enumeration type.
-Such a confirming representation
-is permitted by these rules, and is specially recognized by the compiler so
-that no extra overhead results from the use of such a clause.
-
-If an array has an index type which is an enumeration type to which an
-enumeration clause has been applied, then the array is stored in a compact
-manner.  Consider the declarations:
-
-@example
-type r is (A, B, C);
-for r use (A => 1, B => 5, C => 10);
-type t is array (r) of Character;
-@end example
-
-The array type t corresponds to a vector with exactly three elements and
-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 @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 address-clauses}@anchor{295}@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{296}
-@section Address Clauses
-
-
-@geindex Address Clause
-
-The reference manual allows a general restriction on representation clauses,
-as found in RM 13.1(22):
-
-@quotation
-
-“An implementation need not support representation
-items containing nonstatic expressions, except that
-an implementation should support a representation item
-for a given entity if each nonstatic expression in the
-representation item is a name that statically denotes
-a constant declared before the entity.”
-@end quotation
-
-In practice this is applicable only to address clauses, since this is the
-only case in which a nonstatic expression is permitted by the syntax.  As
-the AARM notes in sections 13.1 (22.a-22.h):
-
-@quotation
-
-22.a   Reason: This is to avoid the following sort of thing:
-
-22.b        X : Integer := F(…);
-Y : Address := G(…);
-for X’Address use Y;
-
-22.c   In the above, we have to evaluate the
-initialization expression for X before we
-know where to put the result.  This seems
-like an unreasonable implementation burden.
-
-22.d   The above code should instead be written
-like this:
-
-22.e        Y : constant Address := G(…);
-X : Integer := F(…);
-for X’Address use Y;
-
-22.f   This allows the expression ‘Y’ to be safely
-evaluated before X is created.
-
-22.g   The constant could be a formal parameter of mode in.
-
-22.h   An implementation can support other nonstatic
-expressions if it wants to.  Expressions of type
-Address are hardly ever static, but their value
-might be known at compile time anyway in many
-cases.
-@end quotation
-
-GNAT does indeed permit many additional cases of nonstatic expressions.  In
-particular, if the type involved is elementary there are no restrictions
-(since in this case, holding a temporary copy of the initialization value,
-if one is present, is inexpensive).  In addition, if there is no implicit or
-explicit initialization, then there are no restrictions.  GNAT will reject
-only the case where all three of these conditions hold:
-
-
-@itemize *
-
-@item 
-The type of the item is non-elementary (e.g., a record or array).
-
-@item 
-There is explicit or implicit initialization required for the object.
-Note that access values are always implicitly initialized.
-
-@item 
-The address value is nonstatic.  Here GNAT is more permissive than the
-RM, and allows the address value to be the address of a previously declared
-stand-alone variable, as long as it does not itself have an address clause.
-
-@example
-Anchor  : Some_Initialized_Type;
-Overlay : Some_Initialized_Type;
-for Overlay'Address use Anchor'Address;
-@end example
-
-However, the prefix of the address clause cannot be an array component, or
-a component of a discriminated record.
-@end itemize
-
-As noted above in section 22.h, address values are typically nonstatic.  In
-particular the To_Address function, even if applied to a literal value, is
-a nonstatic function call.  To avoid this minor annoyance, GNAT provides
-the implementation defined attribute ‘To_Address.  The following two
-expressions have identical values:
-
-@geindex Attribute
-
-@geindex To_Address
-
-@example
-To_Address (16#1234_0000#)
-System'To_Address (16#1234_0000#);
-@end example
-
-except that the second form is considered to be a static expression, and
-thus when used as an address clause value is always permitted.
-
-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
-@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
-value must be consistent with the alignment of the object (which is usually
-the same as the alignment of the type of the object).  If an address clause
-is given that specifies an inappropriately aligned address value, then the
-program execution is erroneous.
-
-Since this source of erroneous behavior can have unfortunate effects on
-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 @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
-@code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also
-suppressed by default on non-strict alignment machines (such as the x86).
-
-In some cases, GNAT does not support an address specification (using either
-form of aspect specification syntax) for the declaration of an object that has
-an indefinite nominal subtype. An object declaration has an indefinite
-nominal subtype if it takes its bounds (for an array type), discriminant
-values (for a discriminated type whose discriminants lack defaults), or tag
-(for a class-wide type) from its initial value, as in
-
-@example
-X : String := Some_Function_Call;
--- String has no constraint, so bounds for X come from function call
-@end example
-
-This restriction does not apply if the size of the object’s initial value is
-known at compile time and the type of the object is not class-wide.
-
-@geindex Export
-
-An address clause cannot be given for an exported object.  More
-understandably the real restriction is that objects with an address
-clause cannot be exported.  This is because such variables are not
-defined by the Ada program, so there is no external object to export.
-
-@geindex Import
-
-It is permissible to give an address clause and a pragma Import for the
-same object.  In this case, the variable is not really defined by the
-Ada program, so there is no external symbol to be linked.  The link name
-and the external name are ignored in this case.  The reason that we allow this
-combination is that it provides a useful idiom to avoid unwanted
-initializations on objects with address clauses.
-
-When an address clause is given for an object that has implicit or
-explicit initialization, then by default initialization takes place.  This
-means that the effect of the object declaration is to overwrite the
-memory at the specified address.  This is almost always not what the
-programmer wants, so GNAT will output a warning:
-
-@example
-with System;
-package G is
-   type R is record
-      M : Integer := 0;
-   end record;
-
-   Ext : R;
-   for Ext'Address use System'To_Address (16#1234_1234#);
-       |
->>> warning: implicit initialization of "Ext" may
-    modify overlaid storage
->>> warning: use pragma Import for "Ext" to suppress
-    initialization (RM B(24))
-
-end G;
-@end example
-
-As indicated by the warning message, the solution is to use a (dummy) pragma
-Import to suppress this initialization.  The pragma tell the compiler that the
-object is declared and initialized elsewhere.  The following package compiles
-without warnings (and the initialization is suppressed):
-
-@example
-with System;
-package G is
-   type R is record
-      M : Integer := 0;
-   end record;
-
-   Ext : R;
-   for Ext'Address use System'To_Address (16#1234_1234#);
-   pragma Import (Ada, Ext);
-end G;
-@end example
-
-A final issue with address clauses involves their use for overlaying
-variables, as in the following example:
-
-@geindex Overlaying of objects
-
-@example
-A : Integer;
-B : Integer;
-for B'Address use A'Address;
-@end example
-
-or alternatively, using the form recommended by the RM:
-
-@example
-A    : Integer;
-Addr : constant Address := A'Address;
-B    : Integer;
-for B'Address use Addr;
-@end example
-
-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, @code{B} should be subject to the following
-implementation advice (RM 13.3(19)):
-
-@quotation
-
-“19  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.”
-@end quotation
-
-GNAT follows this recommendation, and goes further by also applying
-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 @code{Volatile} and implements the
-associated semantics.
-
-Note that when address clause overlays are used in this way, there is an
-issue of unintentional initialization, as shown by this example:
-
-@example
-package Overwrite_Record is
-   type R is record
-      A : Character := 'C';
-      B : Character := 'A';
-   end record;
-   X : Short_Integer := 3;
-   Y : R;
-   for Y'Address use X'Address;
-       |
->>> warning: default initialization of "Y" may
-    modify "X", use pragma Import for "Y" to
-    suppress initialization (RM B.1(24))
-
-end Overwrite_Record;
-@end example
-
-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
-package Overwrite_Record is
-   type R is record
-      A : Character := 'C';
-      B : Character := 'A';
-   end record;
-   X : Short_Integer := 3;
-   Y : R;
-   for Y'Address use X'Address;
-   pragma Import (Ada, Y);
-end Overwrite_Record;
-@end example
-
-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 @code{Initialize_Scalars} is part of the initialization routine
-for the composite object):
-
-@example
-pragma Initialize_Scalars;
-with Ada.Text_IO;  use Ada.Text_IO;
-procedure Overwrite_Array is
-   type Arr is array (1 .. 5) of Integer;
-   X : Arr := (others => 1);
-   A : Arr;
-   for A'Address use X'Address;
-       |
->>> warning: default initialization of "A" may
-    modify "X", use pragma Import for "A" to
-    suppress initialization (RM B.1(24))
-
-begin
-   if X /= Arr'(others => 1) then
-      Put_Line ("X was clobbered");
-   else
-      Put_Line ("X was not clobbered");
-   end if;
-end Overwrite_Array;
-@end example
-
-The above program generates the warning as shown, and at execution
-time, prints @code{X was clobbered}. If the @code{pragma Import} is
-added as suggested:
-
-@example
-pragma Initialize_Scalars;
-with Ada.Text_IO;  use Ada.Text_IO;
-procedure Overwrite_Array is
-   type Arr is array (1 .. 5) of Integer;
-   X : Arr := (others => 1);
-   A : Arr;
-   for A'Address use X'Address;
-   pragma Import (Ada, A);
-begin
-   if X /= Arr'(others => 1) then
-      Put_Line ("X was clobbered");
-   else
-      Put_Line ("X was not clobbered");
-   end if;
-end Overwrite_Array;
-@end example
-
-then the program compiles without the warning and when run will generate
-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{297}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{298}
-@section Use of Address Clauses for Memory-Mapped I/O
-
-
-@geindex Memory-mapped I/O
-
-A common pattern is to use an address clause to map an atomic variable to
-a location in memory that corresponds to a memory-mapped I/O operation or
-operations, for example:
-
-@example
-type Mem_Word is record
-   A,B,C,D : Byte;
-end record;
-pragma Atomic (Mem_Word);
-for Mem_Word_Size use 32;
-
-Mem : Mem_Word;
-for Mem'Address use some-address;
-...
-Temp := Mem;
-Temp.A := 32;
-Mem := Temp;
-@end example
-
-For a full access (reference or modification) of the variable (Mem) in this
-case, as in the above examples, GNAT guarantees that the entire atomic word
-will be accessed, in accordance with the RM C.6(15) clause.
-
-A problem arises with a component access such as:
-
-@example
-Mem.A := 32;
-@end example
-
-Note that the component A is not declared as atomic. This means that it is
-not clear what this assignment means. It could correspond to full word read
-and write as given in the first example, or on architectures that supported
-such an operation it might be a single byte store instruction. The RM does
-not have anything to say in this situation, and GNAT does not make any
-guarantee. The code generated may vary from target to target. GNAT will issue
-a warning in such a case:
-
-@example
-Mem.A := 32;
-|
->>> warning: access to non-atomic component of atomic array,
-    may cause unexpected accesses to atomic object
-@end example
-
-It is best to be explicit in this situation, by either declaring the
-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 @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 effect-of-convention-on-representation}@anchor{299}@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{29a}
-@section Effect of Convention on Representation
-
-
-@geindex Convention
-@geindex effect on representation
-
-Normally the specification of a foreign language convention for a type or
-an object has no effect on the chosen representation.  In particular, the
-representation chosen for data in GNAT generally meets the standard system
-conventions, and for example records are laid out in a manner that is
-consistent with C.  This means that specifying convention C (for example)
-has no effect.
-
-There are four exceptions to this general rule:
-
-
-@itemize *
-
-@item 
-`Convention Fortran and array subtypes'.
-
-If pragma Convention Fortran is specified for an array subtype, then in
-accordance with the implementation advice in section 3.6.2(11) of the
-Ada Reference Manual, the array will be stored in a Fortran-compatible
-column-major manner, instead of the normal default row-major order.
-
-@item 
-`Convention C and enumeration types'
-
-GNAT normally stores enumeration types in 8, 16, or 32 bits as required
-to accommodate all values of the type.  For example, for the enumeration
-type declared by:
-
-@example
-type Color is (Red, Green, Blue);
-@end example
-
-8 bits is sufficient to store all values of the type, so by default, objects
-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 @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.
-
-Note that this treatment applies only to types. If Convention C is given for
-an enumeration object, where the enumeration type is not Convention C, then
-Object_Size bits are allocated. For example, for a normal enumeration type,
-with less than 256 elements, only 8 bits will be allocated for the object.
-Since this may be a surprise in terms of what C expects, GNAT will issue a
-warning in this situation. The warning can be suppressed by giving an explicit
-size clause specifying the desired size.
-
-@item 
-`Convention C/Fortran and Boolean types'
-
-In C, the usual convention for boolean values, that is values used for
-conditions, is that zero represents false, and nonzero values represent
-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 @code{LOGICAL} values (any nonzero
-value represents true).
-
-To accommodate the Fortran and C conventions, if a pragma Convention specifies
-C or Fortran convention for a derived Boolean, as in the following example:
-
-@example
-type C_Switch is new Boolean;
-pragma Convention (C, C_Switch);
-@end example
-
-then the GNAT generated code will treat any nonzero value as true.  For truth
-values generated by GNAT, the conventional value 1 will be used for True, but
-when one of these values is read, any nonzero value is treated as True.
-@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{29b}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{29c}
-@section Conventions and Anonymous Access Types
-
-
-@geindex Anonymous access types
-
-@geindex Convention for anonymous access types
-
-The RM is not entirely clear on convention handling in a number of cases,
-and in particular, it is not clear on the convention to be given to
-anonymous access types in general, and in particular what is to be
-done for the case of anonymous access-to-subprogram.
-
-In GNAT, we decide that if an explicit Convention is applied
-to an object or component, and its type is such an anonymous type,
-then the convention will apply to this anonymous type as well. This
-seems to make sense since it is anomolous in any case to have a
-different convention for an object and its type, and there is clearly
-no way to explicitly specify a convention for an anonymous type, since
-it doesn’t have a name to specify!
-
-Furthermore, we decide that if a convention is applied to a record type,
-then this convention is inherited by any of its components that are of an
-anonymous access type which do not have an explicitly specified convention.
-
-The following program shows these conventions in action:
-
-@example
-package ConvComp is
-   type Foo is range 1 .. 10;
-   type T1 is record
-      A : access function (X : Foo) return Integer;
-      B : Integer;
-   end record;
-   pragma Convention (C, T1);
-
-   type T2 is record
-      A : access function (X : Foo) return Integer;
-      pragma Convention  (C, A);
-      B : Integer;
-   end record;
-   pragma Convention (COBOL, T2);
-
-   type T3 is record
-      A : access function (X : Foo) return Integer;
-      pragma Convention  (COBOL, A);
-      B : Integer;
-   end record;
-   pragma Convention (C, T3);
-
-   type T4 is record
-      A : access function (X : Foo) return Integer;
-      B : Integer;
-   end record;
-   pragma Convention (COBOL, T4);
-
-   function F (X : Foo) return Integer;
-   pragma Convention (C, F);
-
-   function F (X : Foo) return Integer is (13);
-
-   TV1 : T1 := (F'Access, 12);  -- OK
-   TV2 : T2 := (F'Access, 13);  -- OK
-
-   TV3 : T3 := (F'Access, 13);  -- ERROR
-                |
->>> subprogram "F" has wrong convention
->>> does not match access to subprogram declared at line 17
-     38.    TV4 : T4 := (F'Access, 13);  -- ERROR
-                |
->>> subprogram "F" has wrong convention
->>> does not match access to subprogram declared at line 24
-     39. end ConvComp;
-@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 determining-the-representations-chosen-by-gnat}@anchor{29d}@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{29e}
-@section Determining the Representations chosen by GNAT
-
-
-@geindex Representation
-@geindex determination of
-
-@geindex -gnatR (gcc)
-
-Although the descriptions in this section are intended to be complete, it is
-often easier to simply experiment to see what GNAT accepts and what the
-effect is on the layout of types and objects.
-
-As required by the Ada RM, if a representation clause is not accepted, then
-it must be rejected as illegal by the compiler.  However, when a
-representation clause or pragma is accepted, there can still be questions
-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
-@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.
-
-For this purpose, GNAT provides the option `-gnatR'.  If you compile
-with this option, then the compiler will output information on the actual
-representations chosen, in a format similar to source representation
-clauses.  For example, if we compile the package:
-
-@example
-package q is
-   type r (x : boolean) is tagged record
-      case x is
-         when True => S : String (1 .. 100);
-         when False => null;
-      end case;
-   end record;
-
-   type r2 is new r (false) with record
-      y2 : integer;
-   end record;
-
-   for r2 use record
-      y2 at 16 range 0 .. 31;
-   end record;
-
-   type x is record
-      y : character;
-   end record;
-
-   type x1 is array (1 .. 10) of x;
-   for x1'component_size use 11;
-
-   type ia is access integer;
-
-   type Rb1 is array (1 .. 13) of Boolean;
-   pragma Pack (rb1);
-
-   type Rb2 is array (1 .. 65) of Boolean;
-   pragma Pack (rb2);
-
-   type x2 is record
-      l1 : Boolean;
-      l2 : Duration;
-      l3 : Float;
-      l4 : Boolean;
-      l5 : Rb1;
-      l6 : Rb2;
-   end record;
-   pragma Pack (x2);
-end q;
-@end example
-
-using the switch `-gnatR' we obtain the following output:
-
-@example
-Representation information for unit q
--------------------------------------
-
-for r'Size use ??;
-for r'Alignment use 4;
-for r use record
-   x    at 4 range  0 .. 7;
-   _tag at 0 range  0 .. 31;
-   s    at 5 range  0 .. 799;
-end record;
-
-for r2'Size use 160;
-for r2'Alignment use 4;
-for r2 use record
-   x       at  4 range  0 .. 7;
-   _tag    at  0 range  0 .. 31;
-   _parent at  0 range  0 .. 63;
-   y2      at 16 range  0 .. 31;
-end record;
-
-for x'Size use 8;
-for x'Alignment use 1;
-for x use record
-   y at 0 range  0 .. 7;
-end record;
-
-for x1'Size use 112;
-for x1'Alignment use 1;
-for x1'Component_Size use 11;
-
-for rb1'Size use 13;
-for rb1'Alignment use 2;
-for rb1'Component_Size use 1;
-
-for rb2'Size use 72;
-for rb2'Alignment use 1;
-for rb2'Component_Size use 1;
-
-for x2'Size use 224;
-for x2'Alignment use 4;
-for x2 use record
-   l1 at  0 range  0 .. 0;
-   l2 at  0 range  1 .. 64;
-   l3 at 12 range  0 .. 31;
-   l4 at 16 range  0 .. 0;
-   l5 at 16 range  1 .. 13;
-   l6 at 18 range  0 .. 71;
-end record;
-@end example
-
-The Size values are actually the Object_Size, i.e., the default size that
-will be allocated for objects of the type.
-The @code{??} size for type r indicates that we have a variant record, and the
-actual size of objects will depend on the discriminant value.
-
-The Alignment values show the actual alignment chosen by the compiler
-for each record or array type.
-
-The record representation clause for type r shows where all fields
-are placed, including the compiler generated tag field (whose location
-cannot be controlled by the programmer).
-
-The record representation clause for the type extension r2 shows all the
-fields present, including the parent field, which is a copy of the fields
-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 @code{Pack} on these arrays, and the record
-representation clause for type x2 shows how pragma @cite{Pack} affects
-this record type.
-
-In some cases, it may be useful to cut and paste the representation clauses
-generated by the compiler into the original source to fix and guarantee
-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 doc}@anchor{29f}@anchor{gnat_rm/standard_library_routines id1}@anchor{2a0}@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}
-@chapter Standard Library Routines
-
-
-The Ada Reference Manual contains in Annex A a full description of an
-extensive set of standard library routines that can be used in any Ada
-program, and which must be provided by all Ada compilers.  They are
-analogous to the standard C library used by C programs.
-
-GNAT implements all of the facilities described in annex A, and for most
-purposes the description in the Ada Reference Manual, or appropriate Ada
-text book, will be sufficient for making use of these facilities.
-
-In the case of the input-output facilities,
-@ref{f,,The Implementation of Standard I/O},
-gives details on exactly how GNAT interfaces to the
-file system.  For the remaining packages, the Ada Reference Manual
-should be sufficient.  The following is a list of the packages included,
-together with a brief description of the functionality that is provided.
-
-For completeness, references are included to other predefined library
-routines defined in other sections of the Ada Reference Manual (these are
-cross-indexed from Annex A). For further details see the relevant
-package declarations in the run-time library. In particular, a few units
-are not implemented, as marked by the presence of pragma Unimplemented_Unit,
-and in this case the package declaration contains comments explaining why
-the unit is not implemented.
-
-
-@table @asis
-
-@item @code{Ada} `(A.2)'
-
-This is a parent package for all the standard library packages.  It is
-usually included implicitly in your program, and itself contains no
-useful data or routines.
-
-@item @code{Ada.Assertions} `(11.4.2)'
-
-@code{Assertions} provides the @code{Assert} subprograms, and also
-the declaration of the @code{Assertion_Error} exception.
-
-@item @code{Ada.Asynchronous_Task_Control} `(D.11)'
-
-@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} `(9.6)'
-
-@code{Calendar} provides time of day access, and routines for
-manipulating times and durations.
-
-@item @code{Ada.Calendar.Arithmetic} `(9.6.1)'
-
-This package provides additional arithmetic
-operations for @code{Calendar}.
-
-@item @code{Ada.Calendar.Formatting} `(9.6.1)'
-
-This package provides formatting operations for @code{Calendar}.
-
-@item @code{Ada.Calendar.Time_Zones} `(9.6.1)'
-
-This package provides additional @code{Calendar} facilities
-for handling time zones.
-
-@item @code{Ada.Characters} `(A.3.1)'
-
-This is a dummy parent package that contains no useful entities
-
-@item @code{Ada.Characters.Conversions} `(A.3.2)'
-
-This package provides character conversion functions.
-
-@item @code{Ada.Characters.Handling} `(A.3.2)'
-
-This package provides some basic character handling capabilities,
-including classification functions for classes of characters (e.g., test
-for letters, or digits).
-
-@item @code{Ada.Characters.Latin_1} `(A.3.3)'
-
-This package includes a complete set of definitions of the characters
-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 @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} `(A.15)'
-
-This package provides access to the command line parameters and the name
-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.Complex_Text_IO} `(G.1.3)'
-
-This package provides text input and output of complex numbers.
-
-@item @code{Ada.Containers} `(A.18.1)'
-
-A top level package providing a few basic definitions used by all the
-following specific child packages that provide specific kinds of
-containers.
-@end table
-
-@code{Ada.Containers.Bounded_Priority_Queues} `(A.18.31)'
-
-@code{Ada.Containers.Bounded_Synchronized_Queues} `(A.18.29)'
-
-@code{Ada.Containers.Doubly_Linked_Lists} `(A.18.3)'
-
-@code{Ada.Containers.Generic_Array_Sort} `(A.18.26)'
-
-@code{Ada.Containers.Generic_Constrained_Array_Sort} `(A.18.26)'
-
-@code{Ada.Containers.Generic_Sort} `(A.18.26)'
-
-@code{Ada.Containers.Hashed_Maps} `(A.18.5)'
-
-@code{Ada.Containers.Hashed_Sets} `(A.18.8)'
-
-@code{Ada.Containers.Indefinite_Doubly_Linked_Lists} `(A.18.12)'
-
-@code{Ada.Containers.Indefinite_Hashed_Maps} `(A.18.13)'
-
-@code{Ada.Containers.Indefinite_Hashed_Sets} `(A.18.15)'
-
-@code{Ada.Containers.Indefinite_Holders} `(A.18.18)'
-
-@code{Ada.Containers.Indefinite_Multiway_Trees} `(A.18.17)'
-
-@code{Ada.Containers.Indefinite_Ordered_Maps} `(A.18.14)'
-
-@code{Ada.Containers.Indefinite_Ordered_Sets} `(A.18.16)'
-
-@code{Ada.Containers.Indefinite_Vectors} `(A.18.11)'
-
-@code{Ada.Containers.Multiway_Trees} `(A.18.10)'
-
-@code{Ada.Containers.Ordered_Maps} `(A.18.6)'
-
-@code{Ada.Containers.Ordered_Sets} `(A.18.9)'
-
-@code{Ada.Containers.Synchronized_Queue_Interfaces} `(A.18.27)'
-
-@code{Ada.Containers.Unbounded_Priority_Queues} `(A.18.30)'
-
-@code{Ada.Containers.Unbounded_Synchronized_Queues} `(A.18.28)'
-
-@code{Ada.Containers.Vectors} `(A.18.2)'
-
-
-@table @asis
-
-@item @code{Ada.Directories} `(A.16)'
-
-This package provides operations on directories.
-
-@item @code{Ada.Directories.Hierarchical_File_Names} `(A.16.1)'
-
-This package provides additional directory operations handling
-hierarchical file names.
-
-@item @code{Ada.Directories.Information} `(A.16)'
-
-This is an implementation defined package for additional directory
-operations, which is not implemented in GNAT.
-
-@item @code{Ada.Decimal} `(F.2)'
-
-This package provides constants describing the range of decimal numbers
-implemented, and also a decimal divide routine (analogous to the COBOL
-verb DIVIDE … GIVING … REMAINDER …)
-
-@item @code{Ada.Direct_IO} `(A.8.4)'
-
-This package provides input-output using a model of a set of records of
-fixed-length, containing an arbitrary definite Ada type, indexed by an
-integer record number.
-
-@item @code{Ada.Dispatching} `(D.2.1)'
-
-A parent package containing definitions for task dispatching operations.
-
-@item @code{Ada.Dispatching.EDF} `(D.2.6)'
-
-Not implemented in GNAT.
-
-@item @code{Ada.Dispatching.Non_Preemptive} `(D.2.4)'
-
-Not implemented in GNAT.
-
-@item @code{Ada.Dispatching.Round_Robin} `(D.2.5)'
-
-Not implemented in GNAT.
-
-@item @code{Ada.Dynamic_Priorities} `(D.5)'
-
-This package allows the priorities of a task to be adjusted dynamically
-as the task is running.
-
-@item @code{Ada.Environment_Variables} `(A.17)'
-
-This package provides facilities for accessing environment variables.
-
-@item @code{Ada.Exceptions} `(11.4.1)'
-
-This package provides additional information on exceptions, and also
-contains facilities for treating exceptions as data objects, and raising
-exceptions with associated messages.
-
-@item @code{Ada.Execution_Time} `(D.14)'
-
-This package provides CPU clock functionalities. It is not implemented on
-all targets (see package spec for details).
-
-@item @code{Ada.Execution_Time.Group_Budgets} `(D.14.2)'
-
-Not implemented in GNAT.
-
-@item @code{Ada.Execution_Time.Timers} `(D.14.1)’'
-
-Not implemented in GNAT.
-
-@item @code{Ada.Finalization} `(7.6)'
-
-This package contains the declarations and subprograms to support the
-use of controlled types, providing for automatic initialization and
-finalization (analogous to the constructors and destructors of C++).
-
-@item @code{Ada.Float_Text_IO} `(A.10.9)'
-
-A library level instantiation of Text_IO.Float_IO for type Float.
-
-@item @code{Ada.Float_Wide_Text_IO} `(A.10.9)'
-
-A library level instantiation of Wide_Text_IO.Float_IO for type Float.
-
-@item @code{Ada.Float_Wide_Wide_Text_IO} `(A.10.9)'
-
-A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float.
-
-@item @code{Ada.Integer_Text_IO} `(A.10.9)'
-
-A library level instantiation of Text_IO.Integer_IO for type Integer.
-
-@item @code{Ada.Integer_Wide_Text_IO} `(A.10.9)'
-
-A library level instantiation of Wide_Text_IO.Integer_IO for type Integer.
-
-@item @code{Ada.Integer_Wide_Wide_Text_IO} `(A.10.9)'
-
-A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer.
-
-@item @code{Ada.Interrupts} `(C.3.2)'
-
-This package provides facilities for interfacing to interrupts, which
-includes the set of signals or conditions that can be raised and
-recognized as interrupts.
-
-@item @code{Ada.Interrupts.Names} `(C.3.2)'
-
-This package provides the set of interrupt names (actually signal
-or condition names) that can be handled by GNAT.
-
-@item @code{Ada.IO_Exceptions} `(A.13)'
-
-This package defines the set of exceptions that can be raised by use of
-the standard IO packages.
-
-@item @code{Ada.Iterator_Interfaces} `(5.5.1)'
-
-This package provides a generic interface to generalized iterators.
-
-@item @code{Ada.Locales} `(A.19)'
-
-This package provides declarations providing information (Language
-and Country) about the current locale.
-
-@item @code{Ada.Numerics}
-
-This package contains some standard constants and exceptions used
-throughout the numerics packages.  Note that the constants pi and e are
-defined here, and it is better to use these definitions than rolling
-your own.
-
-@item @code{Ada.Numerics.Complex_Arrays} `(G.3.2)'
-
-Provides operations on arrays of complex numbers.
-
-@item @code{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 @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
-@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
-build the type @code{Complex} and @code{Imaginary}.
-
-@item @code{Ada.Numerics.Discrete_Random}
-
-This generic package provides a random number generator suitable for generating
-uniformly distributed values of a specified discrete subtype.
-
-@item @code{Ada.Numerics.Float_Random}
-
-This package provides a random number generator suitable for generating
-uniformly distributed floating point values in the unit interval.
-
-@item @code{Ada.Numerics.Generic_Complex_Elementary_Functions}
-
-This is a generic version of the package that provides the
-implementation of standard elementary functions (such as log and
-trigonometric functions) for an arbitrary complex type.
-
-The following predefined instantiations of this package are provided:
-
-
-@itemize *
-
-@item 
-@code{Short_Float}
-
-@code{Ada.Numerics.Short_Complex_Elementary_Functions}
-
-@item 
-@code{Float}
-
-@code{Ada.Numerics.Complex_Elementary_Functions}
-
-@item 
-@code{Long_Float}
-
-@code{Ada.Numerics.Long_Complex_Elementary_Functions}
-@end itemize
-
-@item @code{Ada.Numerics.Generic_Complex_Types}
-
-This is a generic package that allows the creation of complex types,
-with associated complex arithmetic operations.
-
-The following predefined instantiations of this package exist
-
-
-@itemize *
-
-@item 
-@code{Short_Float}
-
-@code{Ada.Numerics.Short_Complex_Complex_Types}
-
-@item 
-@code{Float}
-
-@code{Ada.Numerics.Complex_Complex_Types}
-
-@item 
-@code{Long_Float}
-
-@code{Ada.Numerics.Long_Complex_Complex_Types}
-@end itemize
-
-@item @code{Ada.Numerics.Generic_Elementary_Functions}
-
-This is a generic package that provides the implementation of standard
-elementary functions (such as log an trigonometric functions) for an
-arbitrary float type.
-
-The following predefined instantiations of this package exist
-
-
-@itemize *
-
-@item 
-@code{Short_Float}
-
-@code{Ada.Numerics.Short_Elementary_Functions}
-
-@item 
-@code{Float}
-
-@code{Ada.Numerics.Elementary_Functions}
-
-@item 
-@code{Long_Float}
-
-@code{Ada.Numerics.Long_Elementary_Functions}
-@end itemize
-
-@item @code{Ada.Numerics.Generic_Real_Arrays} `(G.3.1)'
-
-Generic operations on arrays of reals
-
-@item @code{Ada.Numerics.Real_Arrays} `(G.3.1)'
-
-Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float).
-
-@item @code{Ada.Real_Time} `(D.8)'
-
-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
-the GNAT runtime depends is deliberately reset by some external event,
-then such a backward jump may occur.
-
-@item @code{Ada.Real_Time.Timing_Events} `(D.15)'
-
-Not implemented in GNAT.
-
-@item @code{Ada.Sequential_IO} `(A.8.1)'
-
-This package provides input-output facilities for sequential files,
-which can contain a sequence of values of a single type, which can be
-any Ada type, including indefinite (unconstrained) types.
-
-@item @code{Ada.Storage_IO} `(A.9)'
-
-This package provides a facility for mapping arbitrary Ada types to and
-from a storage buffer.  It is primarily intended for the creation of new
-IO packages.
-
-@item @code{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 (@code{Input},
-@code{Output}, @code{Read} and @code{Write}).
-
-@item @code{Ada.Streams.Stream_IO} `(A.12.1)'
-
-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.
-
-@item @code{Ada.Strings} `(A.4.1)'
-
-This package provides some basic constants used by the string handling
-packages.
-
-@item @code{Ada.Strings.Bounded} `(A.4.4)'
-
-This package provides facilities for handling variable length
-strings.  The bounded model requires a maximum length.  It is thus
-somewhat more limited than the unbounded model, but avoids the use of
-dynamic allocation or finalization.
-
-@item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} `(A.4.10)'
-
-Provides case-insensitive comparisons of bounded strings
-
-@item @code{Ada.Strings.Bounded.Hash} `(A.4.9)'
-
-This package provides a generic hash function for bounded strings
-
-@item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} `(A.4.9)'
-
-This package provides a generic hash function for bounded strings that
-converts the string to be hashed to lower case.
-
-@item @code{Ada.Strings.Bounded.Less_Case_Insensitive} `(A.4.10)'
-
-This package provides a comparison function for bounded strings that works
-in a case insensitive manner by converting to lower case before the comparison.
-
-@item @code{Ada.Strings.Fixed} `(A.4.3)'
-
-This package provides facilities for handling fixed length strings.
-
-@item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} `(A.4.10)'
-
-This package provides an equality function for fixed strings that compares
-the strings after converting both to lower case.
-
-@item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} `(A.4.9)'
-
-This package provides a case insensitive hash function for fixed strings that
-converts the string to lower case before computing the hash.
-
-@item @code{Ada.Strings.Fixed.Less_Case_Insensitive} `(A.4.10)'
-
-This package provides a comparison function for fixed strings that works
-in a case insensitive manner by converting to lower case before the comparison.
-
-@item @code{Ada.Strings.Hash} `(A.4.9)'
-
-This package provides a hash function for strings.
-
-@item @code{Ada.Strings.Hash_Case_Insensitive} `(A.4.9)'
-
-This package provides a hash function for strings that is case insensitive.
-The string is converted to lower case before computing the hash.
-
-@item @code{Ada.Strings.Less_Case_Insensitive} `(A.4.10)'
-
-This package provides a comparison function for\strings that works
-in a case insensitive manner by converting to lower case before the comparison.
-
-@item @code{Ada.Strings.Maps} `(A.4.2)'
-
-This package provides facilities for handling character mappings and
-arbitrarily defined subsets of characters.  For instance it is useful in
-defining specialized translation tables.
-
-@item @code{Ada.Strings.Maps.Constants} `(A.4.6)'
-
-This package provides a standard set of predefined mappings and
-predefined character sets.  For example, the standard upper to lower case
-conversion table is found in this package.  Note that upper to lower case
-conversion is non-trivial if you want to take the entire set of
-characters, including extended characters like E with an acute accent,
-into account.  You should use the mappings in this package (rather than
-adding 32 yourself) to do case mappings.
-
-@item @code{Ada.Strings.Unbounded} `(A.4.5)'
-
-This package provides facilities for handling variable length
-strings.  The unbounded model allows arbitrary length strings, but
-requires the use of dynamic allocation and finalization.
-
-@item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} `(A.4.10)'
-
-Provides case-insensitive comparisons of unbounded strings
-
-@item @code{Ada.Strings.Unbounded.Hash} `(A.4.9)'
-
-This package provides a generic hash function for unbounded strings
-
-@item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} `(A.4.9)'
-
-This package provides a generic hash function for unbounded strings that
-converts the string to be hashed to lower case.
-
-@item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} `(A.4.10)'
-
-This package provides a comparison function for unbounded strings that works
-in a case insensitive manner by converting to lower case before the comparison.
-
-@item @code{Ada.Strings.UTF_Encoding} `(A.4.11)'
-
-This package provides basic definitions for dealing with UTF-encoded strings.
-
-@item @code{Ada.Strings.UTF_Encoding.Conversions} `(A.4.11)'
-
-This package provides conversion functions for UTF-encoded strings.
-@end table
-
-@code{Ada.Strings.UTF_Encoding.Strings} `(A.4.11)'
-
-@code{Ada.Strings.UTF_Encoding.Wide_Strings} `(A.4.11)'
-
-
-@table @asis
-
-@item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} `(A.4.11)'
-
-These packages provide facilities for handling UTF encodings for
-Strings, Wide_Strings and Wide_Wide_Strings.
-@end table
-
-@code{Ada.Strings.Wide_Bounded} `(A.4.7)'
-
-@code{Ada.Strings.Wide_Fixed} `(A.4.7)'
-
-@code{Ada.Strings.Wide_Maps} `(A.4.7)'
-
-
-@table @asis
-
-@item @code{Ada.Strings.Wide_Unbounded} `(A.4.7)'
-
-These packages provide analogous capabilities to the corresponding
-packages without @code{Wide_} in the name, but operate with the types
-@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} `(A.4.7)'
-
-@code{Ada.Strings.Wide_Wide_Fixed} `(A.4.7)'
-
-@code{Ada.Strings.Wide_Wide_Maps} `(A.4.7)'
-
-
-@table @asis
-
-@item @code{Ada.Strings.Wide_Wide_Unbounded} `(A.4.7)'
-
-These packages provide analogous capabilities to the corresponding
-packages without @code{Wide_} in the name, but operate with the types
-@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
-of @code{String} and @code{Character}.
-
-@item @code{Ada.Synchronous_Barriers} `(D.10.1)'
-
-This package provides facilities for synchronizing tasks at a low level
-with barriers.
-
-@item @code{Ada.Synchronous_Task_Control} `(D.10)'
-
-This package provides some standard facilities for controlling task
-communication in a synchronous manner.
-
-@item @code{Ada.Synchronous_Task_Control.EDF} `(D.10)'
-
-Not implemented in GNAT.
-
-@item @code{Ada.Tags}
-
-This package contains definitions for manipulation of the tags of tagged
-values.
-
-@item @code{Ada.Tags.Generic_Dispatching_Constructor} `(3.9)'
-
-This package provides a way of constructing tagged class-wide values given
-only the tag value.
-
-@item @code{Ada.Task_Attributes} `(C.7.2)'
-
-This package provides the capability of associating arbitrary
-task-specific data with separate tasks.
-
-@item @code{Ada.Task_Identification} `(C.7.1)'
-
-This package provides capabilities for task identification.
-
-@item @code{Ada.Task_Termination} `(C.7.3)'
-
-This package provides control over task termination.
-
-@item @code{Ada.Text_IO}
-
-This package provides basic text input-output capabilities for
-character, string and numeric data.  The subpackages of this
-package are listed next. Note that although these are defined
-as subpackages in the RM, they are actually transparently
-implemented as child packages in GNAT, meaning that they
-are only loaded if needed.
-
-@item @code{Ada.Text_IO.Decimal_IO}
-
-Provides input-output facilities for decimal fixed-point types
-
-@item @code{Ada.Text_IO.Enumeration_IO}
-
-Provides input-output facilities for enumeration types.
-
-@item @code{Ada.Text_IO.Fixed_IO}
-
-Provides input-output facilities for ordinary fixed-point types.
-
-@item @code{Ada.Text_IO.Float_IO}
-
-Provides input-output facilities for float types.  The following
-predefined instantiations of this generic package are available:
-
-
-@itemize *
-
-@item 
-@code{Short_Float}
-
-@code{Short_Float_Text_IO}
-
-@item 
-@code{Float}
-
-@code{Float_Text_IO}
-
-@item 
-@code{Long_Float}
-
-@code{Long_Float_Text_IO}
-@end itemize
-
-@item @code{Ada.Text_IO.Integer_IO}
-
-Provides input-output facilities for integer types.  The following
-predefined instantiations of this generic package are available:
-
-
-@itemize *
-
-@item 
-@code{Short_Short_Integer}
-
-@code{Ada.Short_Short_Integer_Text_IO}
-
-@item 
-@code{Short_Integer}
-
-@code{Ada.Short_Integer_Text_IO}
-
-@item 
-@code{Integer}
-
-@code{Ada.Integer_Text_IO}
-
-@item 
-@code{Long_Integer}
-
-@code{Ada.Long_Integer_Text_IO}
-
-@item 
-@code{Long_Long_Integer}
-
-@code{Ada.Long_Long_Integer_Text_IO}
-@end itemize
-
-@item @code{Ada.Text_IO.Modular_IO}
-
-Provides input-output facilities for modular (unsigned) types.
-
-@item @code{Ada.Text_IO.Bounded_IO (A.10.11)}
-
-Provides input-output facilities for bounded strings.
-
-@item @code{Ada.Text_IO.Complex_IO (G.1.3)}
-
-This package provides basic text input-output capabilities for complex
-data.
-
-@item @code{Ada.Text_IO.Editing (F.3.3)}
-
-This package contains routines for edited output, analogous to the use
-of pictures in COBOL.  The picture formats used by this package are a
-close copy of the facility in COBOL.
-
-@item @code{Ada.Text_IO.Text_Streams (A.12.2)}
-
-This package provides a facility that allows Text_IO files to be treated
-as streams, so that the stream attributes can be used for writing
-arbitrary data, including binary data, to Text_IO files.
-
-@item @code{Ada.Text_IO.Unbounded_IO (A.10.12)}
-
-This package provides input-output facilities for unbounded strings.
-
-@item @code{Ada.Unchecked_Conversion (13.9)}
-
-This generic package allows arbitrary conversion from one type to
-another of the same size, providing for breaking the type safety in
-special circumstances.
-
-If the types have the same Size (more accurately the same Value_Size),
-then the effect is simply to transfer the bits from the source to the
-target type without any modification.  This usage is well defined, and
-for simple types whose representation is typically the same across
-all implementations, gives a portable method of performing such
-conversions.
-
-If the types do not have the same size, then the result is implementation
-defined, and thus may be non-portable.  The following describes how GNAT
-handles such unchecked conversion cases.
-
-If the types are of different sizes, and are both discrete types, then
-the effect is of a normal type conversion without any constraint checking.
-In particular if the result type has a larger size, the result will be
-zero or sign extended.  If the result type has a smaller size, the result
-will be truncated by ignoring high order bits.
-
-If the types are of different sizes, and are not both discrete types,
-then the conversion works as though pointers were created to the source
-and target, and the pointer value is converted.  The effect is that bits
-are copied from successive low order storage units and bits of the source
-up to the length of the target type.
-
-A warning is issued if the lengths differ, since the effect in this
-case is implementation dependent, and the above behavior may not match
-that of some other compiler.
-
-A pointer to one type may be converted to a pointer to another type using
-unchecked conversion.  The only case in which the effect is undefined is
-when one or both pointers are pointers to unconstrained array types.  In
-this case, the bounds information may get incorrectly transferred, and in
-particular, GNAT uses double size pointers for such types, and it is
-meaningless to convert between such pointer types.  GNAT will issue a
-warning if the alignment of the target designated type is more strict
-than the alignment of the source designated type (since the result may
-be unaligned in this case).
-
-A pointer other than a pointer to an unconstrained array type may be
-converted to and from System.Address.  Such usage is common in Ada 83
-programs, but note that Ada.Address_To_Access_Conversions is the
-preferred method of performing such conversions in Ada 95 and Ada 2005.
-Neither
-unchecked conversion nor Ada.Address_To_Access_Conversions should be
-used in conjunction with pointers to unconstrained objects, since
-the bounds information cannot be handled correctly in this case.
-
-@item @code{Ada.Unchecked_Deallocation} `(13.11.2)'
-
-This generic package allows explicit freeing of storage previously
-allocated by use of an allocator.
-
-@item @code{Ada.Wide_Text_IO} `(A.11)'
-
-This package is similar to @code{Ada.Text_IO}, except that the external
-file supports wide character representations, and the internal types are
-@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} `(A.11)'
-
-This package is similar to @code{Ada.Text_IO}, except that the external
-file supports wide character representations, and the internal types are
-@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
-
-For packages in Interfaces and System, all the RM defined packages are
-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 doc}@anchor{2a1}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{2a2}@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f}
-@chapter The Implementation of Standard I/O
-
-
-GNAT implements all the required input-output facilities described in
-A.6 through A.14.  These sections of the Ada Reference Manual describe the
-required behavior of these packages from the Ada point of view, and if
-you are writing a portable Ada program that does not need to know the
-exact manner in which Ada maps to the outside world when it comes to
-reading or writing external files, then you do not need to read this
-chapter.  As long as your files are all regular files (not pipes or
-devices), and as long as you write and read the files only from Ada, the
-description in the Ada Reference Manual is sufficient.
-
-However, if you want to do input-output to pipes or other devices, such
-as the keyboard or screen, or if the files you are dealing with are
-either generated by some other language, or to be read by some other
-language, then you need to know more about the details of how the GNAT
-implementation of these input-output facilities behaves.
-
-In this chapter we give a detailed description of exactly how GNAT
-interfaces to the file system.  As always, the sources of the system are
-available to you for answering questions at an even more detailed level,
-but for most purposes the information in this chapter will suffice.
-
-Another reason that you may need to know more about how input-output is
-implemented arises when you have a program written in mixed languages
-where, for example, files are shared between the C and Ada sections of
-the same program.  GNAT provides some additional facilities, in the form
-of additional child library packages, that facilitate this sharing, and
-these additional facilities are also described in this chapter.
-
-@menu
-* Standard I/O Packages:: 
-* FORM Strings:: 
-* Direct_IO:: 
-* Sequential_IO:: 
-* Text_IO:: 
-* Wide_Text_IO:: 
-* Wide_Wide_Text_IO:: 
-* Stream_IO:: 
-* Text Translation:: 
-* Shared Files:: 
-* Filenames encoding:: 
-* File content encoding:: 
-* Open Modes:: 
-* Operations on C Streams:: 
-* Interfacing to C Streams:: 
-
-@end menu
-
-@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2a3}@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2a4}
-@section Standard I/O Packages
-
-
-The Standard I/O packages described in Annex A for
-
-
-@itemize *
-
-@item 
-Ada.Text_IO
-
-@item 
-Ada.Text_IO.Complex_IO
-
-@item 
-Ada.Text_IO.Text_Streams
-
-@item 
-Ada.Wide_Text_IO
-
-@item 
-Ada.Wide_Text_IO.Complex_IO
-
-@item 
-Ada.Wide_Text_IO.Text_Streams
-
-@item 
-Ada.Wide_Wide_Text_IO
-
-@item 
-Ada.Wide_Wide_Text_IO.Complex_IO
-
-@item 
-Ada.Wide_Wide_Text_IO.Text_Streams
-
-@item 
-Ada.Stream_IO
-
-@item 
-Ada.Sequential_IO
-
-@item 
-Ada.Direct_IO
-@end itemize
-
-are implemented using the C
-library streams facility; where
-
-
-@itemize *
-
-@item 
-All files are opened using @code{fopen}.
-
-@item 
-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
-buffering is that provided at the system level in the implementation of the
-library routines that support streams. This facilitates shared use of these
-streams by mixed language programs. Note though that system level buffering is
-explicitly enabled at elaboration of the standard I/O packages and that can
-have an impact on mixed language programs, in particular those using I/O before
-calling the Ada elaboration routine (e.g., adainit). It is recommended to call
-the Ada elaboration routine before performing any I/O or when impractical,
-flush the common I/O streams and in particular Standard_Output before
-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{2a5}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2a6}
-@section FORM Strings
-
-
-The format of a FORM string in GNAT is:
-
-@example
-"keyword=value,keyword=value,...,keyword=value"
-@end example
-
-where letters may be in upper or lower case, and there are no spaces
-between values.  The order of the entries is not important.  Currently
-the following keywords defined.
-
-@example
-TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT]
-SHARED=[YES|NO]
-WCEM=[n|h|u|s|e|8|b]
-ENCODING=[UTF8|8BITS]
-@end example
-
-The use of these parameters is described later in this section. If an
-unrecognized keyword appears in a form string, it is silently ignored
-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{2a7}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2a8}
-@section Direct_IO
-
-
-Direct_IO can only be instantiated for definite types.  This is a
-restriction of the Ada language, which means that the records are fixed
-length (the length being determined by @code{type'Size}, rounded
-up to the next storage unit boundary if necessary).
-
-The records of a Direct_IO file are simply written to the file in index
-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 @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 id5}@anchor{2a9}@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2aa}
-@section Sequential_IO
-
-
-Sequential_IO may be instantiated with either a definite (constrained)
-or indefinite (unconstrained) type.
-
-For the definite type case, the elements written to the file are simply
-the memory images of the data values with no control information of any
-kind.  The resulting file should be read using the same type, no validity
-checking is performed on input.
-
-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 @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, @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 @code{Data_Error}:
-
-@example
-package IO is new Sequential_IO (String);
-F : IO.File_Type;
-S : String (1..4);
-...
-IO.Create (F)
-IO.Write (F, "hello!")
-IO.Reset (F, Mode=>In_File);
-IO.Read (F, S);
-Put_Line (S);
-@end example
-
-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 @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{2ab}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2ac}
-@section Text_IO
-
-
-Text_IO files consist of a stream of characters containing the following
-special control characters:
-
-@example
-LF (line feed, 16#0A#) Line Mark
-FF (form feed, 16#0C#) Page Mark
-@end example
-
-A canonical Text_IO file is defined as one in which the following
-conditions are met:
-
-
-@itemize *
-
-@item 
-The character @code{LF} is used only as a line mark, i.e., to mark the end
-of the line.
-
-@item 
-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
-@code{LF} (line mark) character.
-
-@item 
-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 @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
-pipe) can be read using any of the routines in Text_IO.  The
-semantics in this case will be exactly as defined in the Ada Reference
-Manual, and all the routines in Text_IO are fully implemented.
-
-A text file that does not meet the requirements for a canonical Text_IO
-file has one of the following:
-
-
-@itemize *
-
-@item 
-The file contains @code{FF} characters not immediately following a
-@code{LF} character.
-
-@item 
-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 @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 @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 @code{LF} character is considered
-to end a line, and there is an implied @code{LF} character at the end of
-the file.
-
-@menu
-* Stream Pointer Positioning:: 
-* Reading and Writing Non-Regular Files:: 
-* Get_Immediate:: 
-* Treating Text_IO Files as Streams:: 
-* Text_IO Extensions:: 
-* Text_IO Facilities for Unbounded Strings:: 
-
-@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{2ad}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2ae}
-@subsection Stream Pointer Positioning
-
-
-@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 @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 @code{End_Of_Page} call.
-
-@item 
-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,
-and past a possible page mark following the line mark.  Again Text_IO
-maintains internal flags so that subsequent read operations properly
-handle the logical position.
-@end itemize
-
-These discrepancies have no effect on the observable behavior of
-Text_IO, but if a single Ada stream is shared between a C program and
-Ada program, or shared (using @code{shared=yes} in the form string)
-between two Ada files, then the difference may be observable in some
-situations.
-
-@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2af}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2b0}
-@subsection Reading and Writing Non-Regular Files
-
-
-A non-regular file is a device (such as a keyboard), or a pipe.  Text_IO
-can be used for reading and writing.  Writing is not affected and the
-sequence of characters output is identical to the normal file case, but
-for reading, the behavior of Text_IO is modified to avoid undesirable
-look-ahead as follows:
-
-An input file that is not a regular file is considered to have no page
-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 
-@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.
-
-@item 
-This avoids the need to wait for an extra character to be typed or
-entered from the pipe to complete one of these operations.
-
-@item 
-@code{End_Of_Page} always returns @code{False}
-
-@item 
-@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 @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.
-
-Another important discrepancy when reading non-regular files is that the end
-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 @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{2b1}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2b2}
-@subsection Get_Immediate
-
-
-@geindex Get_Immediate
-
-Get_Immediate returns the next character (including control characters)
-from the input file.  In particular, Get_Immediate will return LF or FF
-characters used as line marks or page marks.  Such operations leave the
-file positioned past the control character, and it is thus not treated
-as having its normal function.  This means that page, line and column
-counts after this kind of Get_Immediate call are set as though the mark
-did not occur.  In the case where a Get_Immediate leaves the file
-positioned between the line mark and page mark (which is not normally
-possible), it is undefined whether the FF character will be treated as a
-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{2b3}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2b4}
-@subsection Treating Text_IO Files as Streams
-
-
-@geindex Stream files
-
-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 @code{LF} and @code{FF} characters may be
-skipped and the effect is similar to that described above for
-@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{2b5}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2b6}
-@subsection Text_IO Extensions
-
-
-@geindex Text_IO extensions
-
-A package GNAT.IO_Aux in the GNAT library provides some useful extensions
-to the standard @code{Text_IO} package:
-
-
-@itemize *
-
-@item 
-function File_Exists (Name : String) return Boolean;
-Determines if a file of the given name exists.
-
-@item 
-function Get_Line return String;
-Reads a string from the standard input file.  The value returned is exactly
-the length of the line that was read.
-
-@item 
-function Get_Line (File : Ada.Text_IO.File_Type) return String;
-Similar, except that the parameter File specifies the file from which
-the string is to be read.
-@end itemize
-
-@node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2b7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2b8}
-@subsection Text_IO Facilities for Unbounded Strings
-
-
-@geindex Text_IO for unbounded strings
-
-@geindex Unbounded_String
-@geindex Text_IO operations
-
-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:
-
-
-@itemize *
-
-@item 
-function Get_Line (File : File_Type) return Unbounded_String;
-Reads a line from the specified file
-and returns the result as an unbounded string.
-
-@item 
-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
-@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 @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, @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 @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
-files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended
-@code{Wide_Text_IO} functionality for unbounded wide strings.
-
-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
-@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 id13}@anchor{2b9}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2ba}
-@section Wide_Text_IO
-
-
-@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:
-
-@example
-WCEM=`x`
-@end example
-
-as part of the FORM string (WCEM = wide character encoding method),
-where @code{x} is one of the following characters
-
-
-@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 
-@headitem
-
-Character
-
-@tab
-
-Encoding
-
-@item
-
-`h'
-
-@tab
-
-Hex ESC encoding
-
-@item
-
-`u'
-
-@tab
-
-Upper half encoding
-
-@item
-
-`s'
-
-@tab
-
-Shift-JIS encoding
-
-@item
-
-`e'
-
-@tab
-
-EUC Encoding
-
-@item
-
-`8'
-
-@tab
-
-UTF-8 encoding
-
-@item
-
-`b'
-
-@tab
-
-Brackets encoding
-
-@end multitable
-
-
-The encoding methods match those that
-can be used in a source
-program, but there is no requirement that the encoding method used for
-the source program be the same as the encoding method used for files,
-and different files may use different encoding methods.
-
-The default encoding method for the standard files, and for opened files
-for which no WCEM parameter is given in the FORM string matches the
-wide character encoding specified for the main program (the default
-being brackets encoding if no coding method was specified with -gnatW).
-
-
-@table @asis
-
-@item `Hex Coding'
-
-In this encoding, a wide character is represented by a five character
-sequence:
-@end table
-
-@example
-ESC a b c d
-@end example
-
-
-@quotation
-
-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
-@code{Wide_Character} set.
-@end quotation
-
-
-@table @asis
-
-@item `Upper Half Coding'
-
-The wide character with encoding 16#abcd#, where the upper bit is on
-(i.e., a is in the range 8-F) is represented as two bytes 16#ab# and
-16#cd#.  The second byte may never 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.
-
-@item `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
-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
-used with this encoding method.
-
-@item `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
-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.
-
-@item `UTF-8 Coding'
-
-A wide character is represented using
-UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
-10646-1/Am.2.  Depending on the character value, the representation
-is a one, two, or three byte sequence:
-@end table
-
-@example
-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
-
-
-@quotation
-
-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
-(The full UTF-8 scheme allows for encoding 31-bit characters as
-6-byte sequences, but in this implementation, all UTF-8 sequences
-of four or more bytes length will raise a Constraint_Error, as
-will all invalid UTF-8 sequences.)
-@end quotation
-
-
-@table @asis
-
-@item `Brackets Coding'
-
-In this encoding, a wide character is represented by the following eight
-character sequence:
-@end table
-
-@example
-[ " a b c d " ]
-@end example
-
-
-@quotation
-
-where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
-characters (using uppercase letters) of the wide character code.  For
-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., @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
-a portable way of encoding source files. In the context of Wide_Text_IO
-or Wide_Wide_Text_IO, it can only be used if the file does not contain
-any instance of the left bracket character other than to encode wide
-character values using the brackets encoding method. In practice it is
-expected that some standard wide character encoding method such
-as UTF-8 will be used for text input output.
-
-If brackets notation is used, then any occurrence of a left bracket
-in the input file which is not the start of a valid wide character
-sequence will cause Constraint_Error to be raised. It is possible to
-encode a left bracket as [“5B”] and Wide_Text_IO and Wide_Wide_Text_IO
-input will interpret this as a left bracket.
-
-However, when a left bracket is output, it will be output as a left bracket
-and not as [“5B”]. We make this decision because for normal use of
-Wide_Text_IO for outputting messages, it is unpleasant to clobber left
-brackets. For example, if we write:
-
-@example
-Put_Line ("Start of output [first run]");
-@end example
-
-we really do not want to have the left bracket in this message clobbered so
-that the output reads:
-@end quotation
-
-@example
-Start of output ["5B"]first run]
-@end example
-
-
-@quotation
-
-In practice brackets encoding is reasonably useful for normal Put_Line use
-since we won’t get confused between left brackets and wide character
-sequences in the output. But for input, or when files are written out
-and read back in, it really makes better sense to use one of the standard
-encoding methods such as UTF-8.
-@end quotation
-
-For the coding schemes other than UTF-8, Hex, or Brackets encoding,
-not all wide character
-values can be represented.  An attempt to output a character that cannot
-be represented using the encoding scheme for the file causes
-Constraint_Error to be raised.  An invalid wide character sequence on
-input also causes Constraint_Error to be raised.
-
-@menu
-* Stream Pointer Positioning: Stream Pointer Positioning<2>. 
-* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 
-
-@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 id14}@anchor{2bb}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2bc}
-@subsection Stream Pointer Positioning
-
-
-@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
-of stream pointer positioning (@ref{2ac,,Text_IO}).  There is one additional
-case:
-
-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
-Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
-@end example
-
-then although the logical position of the file pointer is unchanged by
-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 @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 @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 id15}@anchor{2bd}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2be}
-@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 @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{2bf}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2c0}
-@section Wide_Wide_Text_IO
-
-
-@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:
-
-@example
-WCEM=`x`
-@end example
-
-as part of the FORM string (WCEM = wide character encoding method),
-where @code{x} is one of the following characters
-
-
-@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 
-@headitem
-
-Character
-
-@tab
-
-Encoding
-
-@item
-
-`h'
-
-@tab
-
-Hex ESC encoding
-
-@item
-
-`u'
-
-@tab
-
-Upper half encoding
-
-@item
-
-`s'
-
-@tab
-
-Shift-JIS encoding
-
-@item
-
-`e'
-
-@tab
-
-EUC Encoding
-
-@item
-
-`8'
-
-@tab
-
-UTF-8 encoding
-
-@item
-
-`b'
-
-@tab
-
-Brackets encoding
-
-@end multitable
-
-
-The encoding methods match those that
-can be used in a source
-program, but there is no requirement that the encoding method used for
-the source program be the same as the encoding method used for files,
-and different files may use different encoding methods.
-
-The default encoding method for the standard files, and for opened files
-for which no WCEM parameter is given in the FORM string matches the
-wide character encoding specified for the main program (the default
-being brackets encoding if no coding method was specified with -gnatW).
-
-
-@table @asis
-
-@item `UTF-8 Coding'
-
-A wide character is represented using
-UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
-10646-1/Am.2.  Depending on the character value, the representation
-is a one, two, three, or four byte sequence:
-@end table
-
-@example
-16#000000#-16#00007f#: 2#0xxxxxxx#
-16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
-16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
-16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
-@end example
-
-
-@quotation
-
-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
-characters.
-@end quotation
-
-
-@table @asis
-
-@item `Brackets Coding'
-
-In this encoding, a wide wide character is represented by the following eight
-character sequence if is in wide character range
-@end table
-
-@example
-[ " a b c d " ]
-@end example
-
-
-@quotation
-
-and by the following ten character sequence if not
-@end quotation
-
-@example
-[ " a b c d e f " ]
-@end example
-
-
-@quotation
-
-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, @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., @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,
-such as Shift-JIS, but the other schemes cannot support the full range
-of wide wide characters.
-An attempt to output a character that cannot
-be represented using the encoding scheme for the file causes
-Constraint_Error to be raised.  An invalid wide character sequence on
-input also causes Constraint_Error to be raised.
-
-@menu
-* Stream Pointer Positioning: Stream Pointer Positioning<3>. 
-* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 
-
-@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 id17}@anchor{2c1}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2c2}
-@subsection Stream Pointer Positioning
-
-
-@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
-of stream pointer positioning (@ref{2ac,,Text_IO}).  There is one additional
-case:
-
-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
-Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
-@end example
-
-then although the logical position of the file pointer is unchanged by
-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 @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 @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{2c3}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2c4}
-@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 @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{2c5}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2c6}
-@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
-@code{Stream_Element} is simply a byte.  There are two ways to read or
-write a stream file.
-
-
-@itemize *
-
-@item 
-The operations @code{Read} and @code{Write} directly read or write a
-sequence of stream elements with no control information.
-
-@item 
-The stream attributes applied to a stream file transfer data in the
-manner described for stream attributes.
-@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{2c7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2c8}
-@section Text Translation
-
-
-@code{Text_Translation=xxx} may be used as the Form parameter
-passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx}
-has no effect on Unix systems. Possible values are:
-
-
-@itemize *
-
-@item 
-@code{Yes} or @code{Text} is the default, which means to
-translate LF to/from CR/LF on Windows systems.
-
-@code{No} disables this translation; i.e. it
-uses binary mode. For output files, @code{Text_Translation=No}
-may be used to create Unix-style files on
-Windows.
-
-@item 
-@code{wtext} translation enabled in Unicode mode.
-(corresponds to _O_WTEXT).
-
-@item 
-@code{u8text} translation enabled in Unicode UTF-8 mode.
-(corresponds to O_U8TEXT).
-
-@item 
-@code{u16text} translation enabled in Unicode UTF-16
-mode. (corresponds to_O_U16TEXT).
-@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{2c9}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2ca}
-@section Shared Files
-
-
-Section A.14 of the Ada Reference Manual allows implementations to
-provide a wide variety of behavior if an attempt is made to access the
-same external file with two or more internal files.
-
-To provide a full range of functionality, while at the same time
-minimizing the problems of portability caused by this implementation
-dependence, GNAT handles file sharing as follows:
-
-
-@itemize *
-
-@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 @code{Use_Error} will be
-raised.  Note that a file that is not explicitly closed by the program
-remains open until the program terminates.
-
-@item 
-If the form parameter @code{shared=no} appears in the form string, the
-file can be opened or created with its own separate stream identifier,
-regardless of whether other files sharing the same external file are
-opened.  The exact effect depends on how the C stream routines handle
-multiple accesses to the same external files using separate streams.
-
-@item 
-If the form parameter @code{shared=yes} appears in the form string for
-each of two or more files opened using the same full name, the same
-stream is shared between these files, and the semantics are as described
-in Ada Reference Manual, Section A.14.
-@end itemize
-
-When a program that opens multiple files with the same name is ported
-from another Ada compiler to GNAT, the effect will be that
-@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 @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
-parameter is used in the program.  In this case, you must examine the
-documentation of the new compiler to see if it supports the required
-file sharing semantics, and form strings modified appropriately.  Of
-course it may be the case that the program cannot be ported if the
-target compiler does not support the required functionality.  The best
-approach in writing portable code is to avoid file sharing (and hence
-the use of the @code{shared=xxx} parameter in the form string)
-completely.
-
-One common use of file sharing in Ada 83 is the use of instantiations of
-Sequential_IO on the same file with different types, to achieve
-heterogeneous input-output.  Although this approach will work in GNAT if
-@code{shared=yes} is specified, it is preferable in Ada to use Stream_IO
-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{2cb}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2cc}
-@section Filenames encoding
-
-
-An encoding form parameter can be used to specify the filename
-encoding @code{encoding=xxx}.
-
-
-@itemize *
-
-@item 
-If the form parameter @code{encoding=utf8} appears in the form string, the
-filename must be encoded in UTF-8.
-
-@item 
-If the form parameter @code{encoding=8bits} appears in the form
-string, the filename must be a standard 8bits string.
-@end itemize
-
-In the absence of a @code{encoding=xxx} form parameter, the
-encoding is controlled by the @code{GNAT_CODE_PAGE} environment
-variable. And if not set @code{utf8} is assumed.
-
-
-@table @asis
-
-@item `CP_ACP'
-
-The current system Windows ANSI code page.
-
-@item `CP_UTF8'
-
-UTF-8 encoding
-@end table
-
-This encoding form parameter is only supported on the Windows
-platform. On the other Operating Systems the run-time is supporting
-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{2cd}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2ce}
-@section File content encoding
-
-
-For text files it is possible to specify the encoding to use. This is
-controlled by the by the @code{GNAT_CCS_ENCODING} environment
-variable. And if not set @code{TEXT} is assumed.
-
-The possible values are those supported on Windows:
-
-
-@table @asis
-
-@item `TEXT'
-
-Translated text mode
-
-@item `WTEXT'
-
-Translated unicode encoding
-
-@item `U16TEXT'
-
-Unicode 16-bit encoding
-
-@item `U8TEXT'
-
-Unicode 8-bit encoding
-@end table
-
-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 id24}@anchor{2cf}@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2d0}
-@section Open Modes
-
-
-@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
-
-@code{Open} and @code{Create} Call Modes
-
-@tab
-
-@tab
-
-@item
-
-@tab
-
-`OPEN'
-
-@tab
-
-`CREATE'
-
-@item
-
-Append_File
-
-@tab
-
-“r+”
-
-@tab
-
-“w+”
-
-@item
-
-In_File
-
-@tab
-
-“r”
-
-@tab
-
-“w+”
-
-@item
-
-Out_File (Direct_IO)
-
-@tab
-
-“r+”
-
-@tab
-
-“w”
-
-@item
-
-Out_File (all other cases)
-
-@tab
-
-“w”
-
-@tab
-
-“w”
-
-@item
-
-Inout_File
-
-@tab
-
-“r+”
-
-@tab
-
-“w+”
-
-@end multitable
-
-
-If text file translation is required, then either @code{b} or @code{t}
-is added to the mode, depending on the setting of Text.  Text file
-translation refers to the mapping of CR/LF sequences in an external file
-to LF characters internally.  This mapping only occurs in DOS and
-DOS-like systems, and is not relevant to other systems.
-
-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
-@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 id25}@anchor{2d1}@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2d2}
-@section Operations on C Streams
-
-
-The package @code{Interfaces.C_Streams} provides an Ada program with direct
-access to the C library functions for operations on C streams:
-
-@example
-package Interfaces.C_Streams is
-  -- Note: the reason we do not use the types that are in
-  -- Interfaces.C is that we want to avoid dragging in the
-  -- code in this unit if possible.
-  subtype chars is System.Address;
-  -- Pointer to null-terminated array of characters
-  subtype FILEs is System.Address;
-  -- Corresponds to the C type FILE*
-  subtype voids is System.Address;
-  -- Corresponds to the C type void*
-  subtype int is Integer;
-  subtype long is Long_Integer;
-  -- Note: the above types are subtypes deliberately, and it
-  -- is part of this spec that the above correspondences are
-  -- guaranteed.  This means that it is legitimate to, for
-  -- example, use Integer instead of int.  We provide these
-  -- synonyms for clarity, but in some cases it may be
-  -- convenient to use the underlying types (for example to
-  -- avoid an unnecessary dependency of a spec on the spec
-  -- of this unit).
-  type size_t is mod 2 ** Standard'Address_Size;
-  NULL_Stream : constant FILEs;
-  -- Value returned (NULL in C) to indicate an
-  -- fdopen/fopen/tmpfile error
-  ----------------------------------
-  -- Constants Defined in stdio.h --
-  ----------------------------------
-  EOF : constant int;
-  -- Used by a number of routines to indicate error or
-  -- end of file
-  IOFBF : constant int;
-  IOLBF : constant int;
-  IONBF : constant int;
-  -- Used to indicate buffering mode for setvbuf call
-  SEEK_CUR : constant int;
-  SEEK_END : constant int;
-  SEEK_SET : constant int;
-  -- Used to indicate origin for fseek call
-  function stdin return FILEs;
-  function stdout return FILEs;
-  function stderr return FILEs;
-  -- Streams associated with standard files
-  --------------------------
-  -- Standard C functions --
-  --------------------------
-  -- The functions selected below are ones that are
-  -- available in UNIX (but not necessarily in ANSI C).
-  -- These are very thin interfaces
-  -- which copy exactly the C headers.  For more
-  -- documentation on these functions, see the Microsoft C
-  -- "Run-Time Library Reference" (Microsoft Press, 1990,
-  -- ISBN 1-55615-225-6), which includes useful information
-  -- on system compatibility.
-  procedure clearerr (stream : FILEs);
-  function fclose (stream : FILEs) return int;
-  function fdopen (handle : int; mode : chars) return FILEs;
-  function feof (stream : FILEs) return int;
-  function ferror (stream : FILEs) return int;
-  function fflush (stream : FILEs) return int;
-  function fgetc (stream : FILEs) return int;
-  function fgets (strng : chars; n : int; stream : FILEs)
-      return chars;
-  function fileno (stream : FILEs) return int;
-  function fopen (filename : chars; Mode : chars)
-      return FILEs;
-  -- Note: to maintain target independence, use
-  -- text_translation_required, a boolean variable defined in
-  -- a-sysdep.c to deal with the target dependent text
-  -- translation requirement.  If this variable is set,
-  -- then  b/t should be appended to the standard mode
-  -- argument to set the text translation mode off or on
-  -- as required.
-  function fputc (C : int; stream : FILEs) return int;
-  function fputs (Strng : chars; Stream : FILEs) return int;
-  function fread
-     (buffer : voids;
-      size : size_t;
-      count : size_t;
-      stream : FILEs)
-      return size_t;
-  function freopen
-     (filename : chars;
-      mode : chars;
-      stream : FILEs)
-      return FILEs;
-  function fseek
-     (stream : FILEs;
-      offset : long;
-      origin : int)
-      return int;
-  function ftell (stream : FILEs) return long;
-  function fwrite
-     (buffer : voids;
-      size : size_t;
-      count : size_t;
-      stream : FILEs)
-      return size_t;
-  function isatty (handle : int) return int;
-  procedure mktemp (template : chars);
-  -- The return value (which is just a pointer to template)
-  -- is discarded
-  procedure rewind (stream : FILEs);
-  function rmtmp return int;
-  function setvbuf
-     (stream : FILEs;
-      buffer : chars;
-      mode : int;
-      size : size_t)
-      return int;
-
-  function tmpfile return FILEs;
-  function ungetc (c : int; stream : FILEs) return int;
-  function unlink (filename : chars) return int;
-  ---------------------
-  -- Extra functions --
-  ---------------------
-  -- These functions supply slightly thicker bindings than
-  -- those above.  They are derived from functions in the
-  -- C Run-Time Library, but may do a bit more work than
-  -- just directly calling one of the Library functions.
-  function is_regular_file (handle : int) return int;
-  -- Tests if given handle is for a regular file (result 1)
-  -- or for a non-regular file (pipe or device, result 0).
-  ---------------------------------
-  -- Control of Text/Binary Mode --
-  ---------------------------------
-  -- If text_translation_required is true, then the following
-  -- functions may be used to dynamically switch a file from
-  -- binary to text mode or vice versa.  These functions have
-  -- no effect if text_translation_required is false (i.e., in
-  -- normal UNIX mode).  Use fileno to get a stream handle.
-  procedure set_binary_mode (handle : int);
-  procedure set_text_mode (handle : int);
-  ----------------------------
-  -- Full Path Name support --
-  ----------------------------
-  procedure full_name (nam : chars; buffer : chars);
-  -- Given a NUL terminated string representing a file
-  -- name, returns in buffer a NUL terminated string
-  -- representing the full path name for the file name.
-  -- On systems where it is relevant the   drive is also
-  -- part of the full path name.  It is the responsibility
-  -- of the caller to pass an actual parameter for buffer
-  -- that is big enough for any full path name.  Use
-  -- max_path_len given below as the size of buffer.
-  max_path_len : integer;
-  -- Maximum length of an allowable full path name on the
-  -- system, including a terminating NUL character.
-end Interfaces.C_Streams;
-@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 id26}@anchor{2d3}@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2d4}
-@section Interfacing to C Streams
-
-
-The packages in this section permit interfacing Ada files to C Stream
-operations.
-
-@example
-with Interfaces.C_Streams;
-package Ada.Sequential_IO.C_Streams is
-   function C_Stream (F : File_Type)
-      return Interfaces.C_Streams.FILEs;
-   procedure Open
-     (File : in out File_Type;
-      Mode : in File_Mode;
-      C_Stream : in Interfaces.C_Streams.FILEs;
-      Form : in String := "");
-end Ada.Sequential_IO.C_Streams;
-
- with Interfaces.C_Streams;
- package Ada.Direct_IO.C_Streams is
-    function C_Stream (F : File_Type)
-       return Interfaces.C_Streams.FILEs;
-    procedure Open
-      (File : in out File_Type;
-       Mode : in File_Mode;
-       C_Stream : in Interfaces.C_Streams.FILEs;
-       Form : in String := "");
- end Ada.Direct_IO.C_Streams;
-
- with Interfaces.C_Streams;
- package Ada.Text_IO.C_Streams is
-    function C_Stream (F : File_Type)
-       return Interfaces.C_Streams.FILEs;
-    procedure Open
-      (File : in out File_Type;
-       Mode : in File_Mode;
-       C_Stream : in Interfaces.C_Streams.FILEs;
-       Form : in String := "");
- end Ada.Text_IO.C_Streams;
-
- with Interfaces.C_Streams;
- package Ada.Wide_Text_IO.C_Streams is
-    function C_Stream (F : File_Type)
-       return Interfaces.C_Streams.FILEs;
-    procedure Open
-      (File : in out File_Type;
-       Mode : in File_Mode;
-       C_Stream : in Interfaces.C_Streams.FILEs;
-       Form : in String := "");
-end Ada.Wide_Text_IO.C_Streams;
-
- with Interfaces.C_Streams;
- package Ada.Wide_Wide_Text_IO.C_Streams is
-    function C_Stream (F : File_Type)
-       return Interfaces.C_Streams.FILEs;
-    procedure Open
-      (File : in out File_Type;
-       Mode : in File_Mode;
-       C_Stream : in Interfaces.C_Streams.FILEs;
-       Form : in String := "");
-end Ada.Wide_Wide_Text_IO.C_Streams;
-
-with Interfaces.C_Streams;
-package Ada.Stream_IO.C_Streams is
-   function C_Stream (F : File_Type)
-      return Interfaces.C_Streams.FILEs;
-   procedure Open
-     (File : in out File_Type;
-      Mode : in File_Mode;
-      C_Stream : in Interfaces.C_Streams.FILEs;
-      Form : in String := "");
-end Ada.Stream_IO.C_Streams;
-@end example
-
-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
-@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 @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 doc}@anchor{2d5}@anchor{gnat_rm/the_gnat_library id1}@anchor{2d6}@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}
-@chapter The GNAT Library
-
-
-The GNAT library contains a number of general and special purpose packages.
-It represents functionality that the GNAT developers have found useful, and
-which is made available to GNAT users.  The packages described here are fully
-supported, and upwards compatibility will be maintained in future releases,
-so you can use these facilities with the confidence that the same functionality
-will be available in future releases.
-
-The chapter here simply gives a brief summary of the facilities available.
-The full documentation is found in the spec file for the package.  The full
-sources of these library packages, including both spec and body, are provided
-with all GNAT releases.  For example, to find out the full specifications of
-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 @code{with}
-clause) is given, followed by the name of the corresponding spec file in
-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 @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.
-
-@menu
-* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 
-* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 
-* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 
-* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 
-* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 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. 
-* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 
-* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 
-* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 
-* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 
-* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 
-* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 
-* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 
-* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): 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 a-swuwti ads. 
-* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 
-* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. 
-* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 
-* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 
-* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 
-* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 
-* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 
-* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): 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 a-ztcstr ads. 
-* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 
-* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 
-* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 
-* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 
-* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 
-* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 
-* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 
-* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 
-* GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. 
-* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 
-* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. 
-* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 
-* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 
-* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 
-* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 
-* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 
-* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 
-* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 
-* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 
-* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 
-* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 
-* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 
-* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 
-* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 
-* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 
-* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 
-* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 
-* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 
-* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 
-* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 
-* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 
-* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 
-* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 
-* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 
-* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 
-* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 
-* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 
-* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 
-* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 
-* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 
-* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 
-* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. 
-* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 
-* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 
-* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 
-* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 
-* GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. 
-* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 
-* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 
-* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 
-* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 
-* GNAT.IO (g-io.ads): GNAT IO g-io ads. 
-* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 
-* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 
-* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 
-* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 
-* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 
-* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 
-* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 
-* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 
-* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 
-* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 
-* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 
-* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 
-* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 
-* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 
-* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 
-* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 
-* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 
-* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 
-* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 
-* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 
-* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 
-* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 
-* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 
-* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 
-* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 
-* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 
-* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 
-* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 
-* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 
-* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 
-* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 
-* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 
-* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 
-* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 
-* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 
-* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 
-* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 
-* GNAT.Table (g-table.ads): GNAT Table g-table ads. 
-* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 
-* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 
-* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 
-* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 
-* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 
-* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 
-* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 
-* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 
-* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 
-* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 
-* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 
-* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 
-* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 
-* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 
-* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 
-* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 
-* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 
-* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 
-* System.Assertions (s-assert.ads): System Assertions s-assert ads. 
-* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 
-* System.Memory (s-memory.ads): System Memory s-memory ads. 
-* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 
-* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 
-* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 
-* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 
-* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 
-* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 
-* System.Rident (s-rident.ads): System Rident s-rident ads. 
-* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 
-* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 
-* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 
-* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon 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 ada-characters-latin-9-a-chlat9-ads}@anchor{2d7}@anchor{gnat_rm/the_gnat_library id2}@anchor{2d8}
-@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 @code{Ada.Characters}
-provides a set of definitions corresponding to those in the
-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{2d9}@anchor{gnat_rm/the_gnat_library id3}@anchor{2da}
-@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 @code{Ada.Characters}
-provides a set of definitions corresponding to those in the
-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 ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2db}@anchor{gnat_rm/the_gnat_library id4}@anchor{2dc}
-@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 @code{Ada.Characters}
-provides a set of definitions corresponding to those in the
-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{2dd}@anchor{gnat_rm/the_gnat_library id5}@anchor{2de}
-@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 @code{Ada.Characters}
-provides a set of definitions corresponding to those in the
-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 Bounded_Holders a-coboho 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{2df}@anchor{gnat_rm/the_gnat_library id6}@anchor{2e0}
-@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 @code{Ada.Characters}
-provides a set of definitions corresponding to those in the
-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 Bounded_Holders a-coboho ads,Ada Command_Line Environment a-colien ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2e1}@anchor{gnat_rm/the_gnat_library id7}@anchor{2e2}
-@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 @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{2e3}@anchor{gnat_rm/the_gnat_library id8}@anchor{2e4}
-@section @code{Ada.Command_Line.Environment} (@code{a-colien.ads})
-
-
-@geindex Ada.Command_Line.Environment (a-colien.ads)
-
-@geindex Environment entries
-
-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 ada-command-line-remove-a-colire-ads}@anchor{2e5}@anchor{gnat_rm/the_gnat_library id9}@anchor{2e6}
-@section @code{Ada.Command_Line.Remove} (@code{a-colire.ads})
-
-
-@geindex Ada.Command_Line.Remove (a-colire.ads)
-
-@geindex Removing command line arguments
-
-@geindex Command line
-@geindex argument removal
-
-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 @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{2e7}@anchor{gnat_rm/the_gnat_library id10}@anchor{2e8}
-@section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads})
-
-
-@geindex Ada.Command_Line.Response_File (a-clrefi.ads)
-
-@geindex Response file for command line
-
-@geindex Command line
-@geindex response file
-
-@geindex Command line
-@geindex handling long command lines
-
-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 ada-direct-io-c-streams-a-diocst-ads}@anchor{2e9}@anchor{gnat_rm/the_gnat_library id11}@anchor{2ea}
-@section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads})
-
-
-@geindex Ada.Direct_IO.C_Streams (a-diocst.ads)
-
-@geindex C Streams
-@geindex Interfacing with Direct_IO
-
-This package provides subprograms that allow interfacing between
-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 ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2eb}@anchor{gnat_rm/the_gnat_library id12}@anchor{2ec}
-@section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads})
-
-
-@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
-
-@geindex Null_Occurrence
-@geindex testing for
-
-This child subprogram provides a way of testing for the null
-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 ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2ed}@anchor{gnat_rm/the_gnat_library id13}@anchor{2ee}
-@section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads})
-
-
-@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
-
-@geindex Null_Occurrence
-@geindex testing for
-
-This child subprogram is used for handling otherwise unhandled
-exceptions (hence the name last chance), and perform clean ups before
-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{2ef}@anchor{gnat_rm/the_gnat_library id14}@anchor{2f0}
-@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 (@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{2f1}@anchor{gnat_rm/the_gnat_library id15}@anchor{2f2}
-@section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads})
-
-
-@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads)
-
-@geindex C Streams
-@geindex Interfacing with Sequential_IO
-
-This package provides subprograms that allow interfacing between
-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 ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{2f3}@anchor{gnat_rm/the_gnat_library id16}@anchor{2f4}
-@section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads})
-
-
-@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
-
-@geindex C Streams
-@geindex Interfacing with Stream_IO
-
-This package provides subprograms that allow interfacing between
-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{2f5}@anchor{gnat_rm/the_gnat_library id17}@anchor{2f6}
-@section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads})
-
-
-@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
-
-@geindex Unbounded_String
-@geindex IO support
-
-@geindex Text_IO
-@geindex extensions for unbounded strings
-
-This package provides subprograms for Text_IO for unbounded
-strings, avoiding the necessity for an intermediate operation
-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 ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{2f7}@anchor{gnat_rm/the_gnat_library id18}@anchor{2f8}
-@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads})
-
-
-@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
-
-@geindex Unbounded_Wide_String
-@geindex IO support
-
-@geindex Text_IO
-@geindex extensions for unbounded wide strings
-
-This package provides subprograms for Text_IO for unbounded
-wide strings, avoiding the necessity for an intermediate operation
-with ordinary wide strings.
-
-@node Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Task_Initialization a-tasini 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{2f9}@anchor{gnat_rm/the_gnat_library id19}@anchor{2fa}
-@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)
-
-@geindex Unbounded_Wide_Wide_String
-@geindex IO support
-
-@geindex Text_IO
-@geindex extensions for unbounded wide wide strings
-
-This package provides subprograms for Text_IO for unbounded
-wide wide strings, avoiding the necessity for an intermediate operation
-with ordinary wide wide strings.
-
-@node Ada Task_Initialization a-tasini ads,Ada Text_IO C_Streams a-tiocst ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-task-initialization-a-tasini-ads}@anchor{2fb}@anchor{gnat_rm/the_gnat_library id20}@anchor{2fc}
-@section @code{Ada.Task_Initialization} (@code{a-tasini.ads})
-
-
-@geindex Ada.Task_Initialization (a-tasini.ads)
-
-This package provides a way to set a global initialization handler that
-is automatically invoked whenever a task is activated. Handlers are
-parameterless procedures. Note that such a handler is only invoked for
-those tasks activated after the handler is set.
-
-@node Ada Text_IO C_Streams a-tiocst ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Task_Initialization a-tasini ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{2fd}@anchor{gnat_rm/the_gnat_library id21}@anchor{2fe}
-@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 `@w{`}Text_IO`@w{`}
-
-This package provides subprograms that allow interfacing between
-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 ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{2ff}@anchor{gnat_rm/the_gnat_library id22}@anchor{300}
-@section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads})
-
-
-@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)
-
-@geindex Text_IO resetting standard files
-
-This procedure is used to reset the status of the standard files used
-by Ada.Text_IO.  This is useful in a situation (such as a restart in an
-embedded application) where the status of the files may change during
-execution (for example a standard input file may be redefined to be
-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 ada-wide-characters-unicode-a-wichun-ads}@anchor{301}@anchor{gnat_rm/the_gnat_library id23}@anchor{302}
-@section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads})
-
-
-@geindex Ada.Wide_Characters.Unicode (a-wichun.ads)
-
-@geindex Unicode categorization
-@geindex Wide_Character
-
-This package provides subprograms that allow categorization of
-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{303}@anchor{gnat_rm/the_gnat_library id24}@anchor{304}
-@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 `@w{`}Wide_Text_IO`@w{`}
-
-This package provides subprograms that allow interfacing between
-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{305}@anchor{gnat_rm/the_gnat_library id25}@anchor{306}
-@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads})
-
-
-@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)
-
-@geindex Wide_Text_IO resetting standard files
-
-This procedure is used to reset the status of the standard files used
-by Ada.Wide_Text_IO.  This is useful in a situation (such as a restart in an
-embedded application) where the status of the files may change during
-execution (for example a standard input file may be redefined to be
-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 ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{307}@anchor{gnat_rm/the_gnat_library id26}@anchor{308}
-@section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads})
-
-
-@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
-
-@geindex Unicode categorization
-@geindex Wide_Wide_Character
-
-This package provides subprograms that allow categorization of
-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 ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{309}@anchor{gnat_rm/the_gnat_library id27}@anchor{30a}
-@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 `@w{`}Wide_Wide_Text_IO`@w{`}
-
-This package provides subprograms that allow interfacing between
-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 ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{30b}@anchor{gnat_rm/the_gnat_library id28}@anchor{30c}
-@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)
-
-@geindex Wide_Wide_Text_IO resetting standard files
-
-This procedure is used to reset the status of the standard files used
-by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a
-restart in an embedded application) where the status of the files may
-change during execution (for example a standard input file may be
-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{30d}@anchor{gnat_rm/the_gnat_library id29}@anchor{30e}
-@section @code{GNAT.Altivec} (@code{g-altive.ads})
-
-
-@geindex GNAT.Altivec (g-altive.ads)
-
-@geindex AltiVec
-
-This is the root package of the GNAT AltiVec binding. It provides
-definitions of constants and types common to all the versions of the
-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 gnat-altivec-conversions-g-altcon-ads}@anchor{30f}@anchor{gnat_rm/the_gnat_library id30}@anchor{310}
-@section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads})
-
-
-@geindex GNAT.Altivec.Conversions (g-altcon.ads)
-
-@geindex AltiVec
-
-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 gnat-altivec-vector-operations-g-alveop-ads}@anchor{311}@anchor{gnat_rm/the_gnat_library id31}@anchor{312}
-@section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads})
-
-
-@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads)
-
-@geindex AltiVec
-
-This package exposes the Ada interface to the AltiVec operations on
-vector objects. A soft emulation is included by default in the GNAT
-library. The hard binding is provided as a separate package. This unit
-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{313}@anchor{gnat_rm/the_gnat_library id32}@anchor{314}
-@section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads})
-
-
-@geindex GNAT.Altivec.Vector_Types (g-alvety.ads)
-
-@geindex AltiVec
-
-This package exposes the various vector types part of the Ada binding
-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{315}@anchor{gnat_rm/the_gnat_library id33}@anchor{316}
-@section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads})
-
-
-@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads)
-
-@geindex AltiVec
-
-This package provides public ‘View’ data types from/to which private
-vector representations can be converted via
-GNAT.Altivec.Conversions. This allows convenient access to individual
-vector elements and provides a simple way to initialize vector
-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{317}@anchor{gnat_rm/the_gnat_library id34}@anchor{318}
-@section @code{GNAT.Array_Split} (@code{g-arrspl.ads})
-
-
-@geindex GNAT.Array_Split (g-arrspl.ads)
-
-@geindex Array splitter
-
-Useful array-manipulation routines: given a set of separators, split
-an array wherever the separators appear, and provide direct access
-to the resulting slices.
-
-@node GNAT AWK g-awk ads,GNAT Binary_Search g-binsea ads,GNAT Array_Split g-arrspl ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{319}@anchor{gnat_rm/the_gnat_library id35}@anchor{31a}
-@section @code{GNAT.AWK} (@code{g-awk.ads})
-
-
-@geindex GNAT.AWK (g-awk.ads)
-
-@geindex Parsing
-
-@geindex AWK
-
-Provides AWK-like parsing functions, with an easy interface for parsing one
-or more files containing formatted data.  The file is viewed as a database
-where each record is a line and a field is a data element in this line.
-
-@node GNAT Binary_Search g-binsea ads,GNAT Bind_Environment g-binenv ads,GNAT AWK g-awk ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-binary-search-g-binsea-ads}@anchor{31b}@anchor{gnat_rm/the_gnat_library id36}@anchor{31c}
-@section @code{GNAT.Binary_Search} (@code{g-binsea.ads})
-
-
-@geindex GNAT.Binary_Search (g-binsea.ads)
-
-@geindex Binary search
-
-Allow binary search of a sorted array (or of an array-like container;
-the generic does not reference the array directly).
-
-@node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT Binary_Search g-binsea ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{31d}@anchor{gnat_rm/the_gnat_library id37}@anchor{31e}
-@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 @code{-V} binder command
-line switch.
-
-@node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{31f}@anchor{gnat_rm/the_gnat_library id38}@anchor{320}
-@section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads})
-
-
-@geindex GNAT.Branch_Prediction (g-brapre.ads)
-
-@geindex Branch Prediction
-
-Provides routines giving hints to the branch predictor of the code generator.
-
-@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id39}@anchor{322}
-@section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads})
-
-
-@geindex GNAT.Bounded_Buffers (g-boubuf.ads)
-
-@geindex Parsing
-
-@geindex Bounded Buffers
-
-Provides a concurrent generic bounded buffer abstraction.  Instances are
-useful directly or as parts of the implementations of other abstractions,
-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 gnat-bounded-mailboxes-g-boumai-ads}@anchor{323}@anchor{gnat_rm/the_gnat_library id40}@anchor{324}
-@section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads})
-
-
-@geindex GNAT.Bounded_Mailboxes (g-boumai.ads)
-
-@geindex Parsing
-
-@geindex Mailboxes
-
-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{325}@anchor{gnat_rm/the_gnat_library id41}@anchor{326}
-@section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads})
-
-
-@geindex GNAT.Bubble_Sort (g-bubsor.ads)
-
-@geindex Sorting
-
-@geindex Bubble sort
-
-Provides a general implementation of bubble sort usable for sorting arbitrary
-data items.  Exchange and comparison procedures are provided by passing
-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 gnat-bubble-sort-a-g-busora-ads}@anchor{327}@anchor{gnat_rm/the_gnat_library id42}@anchor{328}
-@section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads})
-
-
-@geindex GNAT.Bubble_Sort_A (g-busora.ads)
-
-@geindex Sorting
-
-@geindex Bubble sort
-
-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 @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 gnat-bubble-sort-g-g-busorg-ads}@anchor{329}@anchor{gnat_rm/the_gnat_library id43}@anchor{32a}
-@section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads})
-
-
-@geindex GNAT.Bubble_Sort_G (g-busorg.ads)
-
-@geindex Sorting
-
-@geindex Bubble sort
-
-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{32b}@anchor{gnat_rm/the_gnat_library id44}@anchor{32c}
-@section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads})
-
-
-@geindex GNAT.Byte_Order_Mark (g-byorma.ads)
-
-@geindex UTF-8 representation
-
-@geindex Wide characte representations
-
-Provides a routine which given a string, reads the start of the string to
-see whether it is one of the standard byte order marks (BOM’s) which signal
-the encoding of the string. The routine includes detection of special XML
-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{32d}@anchor{gnat_rm/the_gnat_library id45}@anchor{32e}
-@section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads})
-
-
-@geindex GNAT.Byte_Swapping (g-bytswa.ads)
-
-@geindex Byte swapping
-
-@geindex Endianness
-
-General routines for swapping the bytes in 2-, 4-, and 8-byte quantities.
-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 gnat-calendar-g-calend-ads}@anchor{32f}@anchor{gnat_rm/the_gnat_library id46}@anchor{330}
-@section @code{GNAT.Calendar} (@code{g-calend.ads})
-
-
-@geindex GNAT.Calendar (g-calend.ads)
-
-@geindex Calendar
-
-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{331}@anchor{gnat_rm/the_gnat_library id47}@anchor{332}
-@section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads})
-
-
-@geindex Calendar
-
-@geindex Time
-
-@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 gnat-crc32-g-crc32-ads}@anchor{333}@anchor{gnat_rm/the_gnat_library id48}@anchor{334}
-@section @code{GNAT.CRC32} (@code{g-crc32.ads})
-
-
-@geindex GNAT.CRC32 (g-crc32.ads)
-
-@geindex CRC32
-
-@geindex Cyclic Redundancy Check
-
-This package implements the CRC-32 algorithm.  For a full description
-of this algorithm see
-`Computation of Cyclic Redundancy Checks via Table Look-Up',
-@cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013,
-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{335}@anchor{gnat_rm/the_gnat_library id49}@anchor{336}
-@section @code{GNAT.Case_Util} (@code{g-casuti.ads})
-
-
-@geindex GNAT.Case_Util (g-casuti.ads)
-
-@geindex Casing utilities
-
-@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 @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 gnat-cgi-g-cgi-ads}@anchor{337}@anchor{gnat_rm/the_gnat_library id50}@anchor{338}
-@section @code{GNAT.CGI} (@code{g-cgi.ads})
-
-
-@geindex GNAT.CGI (g-cgi.ads)
-
-@geindex CGI (Common Gateway Interface)
-
-This is a package for interfacing a GNAT program with a Web server via the
-Common Gateway Interface (CGI).  Basically this package parses the CGI
-parameters, which are a set of key/value pairs sent by the Web server.  It
-builds a table whose index is the key and provides some services to deal
-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{339}@anchor{gnat_rm/the_gnat_library id51}@anchor{33a}
-@section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads})
-
-
-@geindex GNAT.CGI.Cookie (g-cgicoo.ads)
-
-@geindex CGI (Common Gateway Interface) cookie support
-
-@geindex Cookie support in CGI
-
-This is a package to interface a GNAT program with a Web server via the
-Common Gateway Interface (CGI).  It exports services to deal with Web
-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{33b}@anchor{gnat_rm/the_gnat_library id52}@anchor{33c}
-@section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads})
-
-
-@geindex GNAT.CGI.Debug (g-cgideb.ads)
-
-@geindex CGI (Common Gateway Interface) debugging
-
-This is a package to help debugging CGI (Common Gateway Interface)
-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 gnat-command-line-g-comlin-ads}@anchor{33d}@anchor{gnat_rm/the_gnat_library id53}@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 @code{Ada.Command_Line} facilities,
-including the ability to scan for named switches with optional parameters
-and expand file names using wildcard 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{33f}@anchor{gnat_rm/the_gnat_library id54}@anchor{340}
-@section @code{GNAT.Compiler_Version} (@code{g-comver.ads})
-
-
-@geindex GNAT.Compiler_Version (g-comver.ads)
-
-@geindex Compiler Version
-
-@geindex Version
-@geindex of compiler
-
-Provides a routine for obtaining the version of the compiler used to
-compile the program. More accurately this is the version of the binder
-used to bind the program (this will normally be the same as the version
-of the compiler if a consistent tool set is used to compile all units
-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{341}@anchor{gnat_rm/the_gnat_library id55}@anchor{342}
-@section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads})
-
-
-@geindex GNAT.Ctrl_C (g-ctrl_c.ads)
-
-@geindex Interrupt
-
-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 gnat-current-exception-g-curexc-ads}@anchor{343}@anchor{gnat_rm/the_gnat_library id56}@anchor{344}
-@section @code{GNAT.Current_Exception} (@code{g-curexc.ads})
-
-
-@geindex GNAT.Current_Exception (g-curexc.ads)
-
-@geindex Current exception
-
-@geindex Exception retrieval
-
-Provides access to information on the current exception that has been raised
-without the need for using the Ada 95 / Ada 2005 exception choice parameter
-specification syntax.
-This is particularly useful in simulating typical facilities for
-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{345}@anchor{gnat_rm/the_gnat_library id57}@anchor{346}
-@section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads})
-
-
-@geindex GNAT.Debug_Pools (g-debpoo.ads)
-
-@geindex Debugging
-
-@geindex Debug pools
-
-@geindex Memory corruption debugging
-
-Provide a debugging storage pools that helps tracking memory corruption
-problems.
-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{347}@anchor{gnat_rm/the_gnat_library id58}@anchor{348}
-@section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads})
-
-
-@geindex GNAT.Debug_Utilities (g-debuti.ads)
-
-@geindex Debugging
-
-Provides a few useful utilities for debugging purposes, including conversion
-to and from string images of address values. Supports both C and Ada formats
-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{349}@anchor{gnat_rm/the_gnat_library id59}@anchor{34a}
-@section @code{GNAT.Decode_String} (@code{g-decstr.ads})
-
-
-@geindex GNAT.Decode_String (g-decstr.ads)
-
-@geindex Decoding strings
-
-@geindex String decoding
-
-@geindex Wide character encoding
-
-@geindex UTF-8
-
-@geindex Unicode
-
-A generic package providing routines for decoding wide character and wide wide
-character strings encoded as sequences of 8-bit characters using a specified
-encoding method. Includes validation routines, and also routines for stepping
-to next or previous encoded character in an encoded string.
-Useful in conjunction with Unicode character coding. Note there is a
-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{34b}@anchor{gnat_rm/the_gnat_library id60}@anchor{34c}
-@section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads})
-
-
-@geindex GNAT.Decode_UTF8_String (g-deutst.ads)
-
-@geindex Decoding strings
-
-@geindex Decoding UTF-8 strings
-
-@geindex UTF-8 string decoding
-
-@geindex Wide character decoding
-
-@geindex UTF-8
-
-@geindex Unicode
-
-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 gnat-directory-operations-g-dirope-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id61}@anchor{34e}
-@section @code{GNAT.Directory_Operations} (@code{g-dirope.ads})
-
-
-@geindex GNAT.Directory_Operations (g-dirope.ads)
-
-@geindex Directory operations
-
-Provides a set of routines for manipulating directories, including changing
-the current directory, making new directories, and scanning the files in a
-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 gnat-directory-operations-iteration-g-diopit-ads}@anchor{34f}@anchor{gnat_rm/the_gnat_library id62}@anchor{350}
-@section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads})
-
-
-@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads)
-
-@geindex Directory operations iteration
-
-A child unit of GNAT.Directory_Operations providing additional operations
-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 gnat-dynamic-htables-g-dynhta-ads}@anchor{351}@anchor{gnat_rm/the_gnat_library id63}@anchor{352}
-@section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads})
-
-
-@geindex GNAT.Dynamic_HTables (g-dynhta.ads)
-
-@geindex Hash tables
-
-A generic implementation of hash tables that can be used to hash arbitrary
-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 @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
-@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{353}@anchor{gnat_rm/the_gnat_library id64}@anchor{354}
-@section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads})
-
-
-@geindex GNAT.Dynamic_Tables (g-dyntab.ads)
-
-@geindex Table implementation
-
-@geindex Arrays
-@geindex extendable
-
-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 @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
-@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 gnat-encode-string-g-encstr-ads}@anchor{355}@anchor{gnat_rm/the_gnat_library id65}@anchor{356}
-@section @code{GNAT.Encode_String} (@code{g-encstr.ads})
-
-
-@geindex GNAT.Encode_String (g-encstr.ads)
-
-@geindex Encoding strings
-
-@geindex String encoding
-
-@geindex Wide character encoding
-
-@geindex UTF-8
-
-@geindex Unicode
-
-A generic package providing routines for encoding wide character and wide
-wide character strings as sequences of 8-bit characters using a specified
-encoding method. Useful in conjunction with Unicode character coding.
-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{357}@anchor{gnat_rm/the_gnat_library id66}@anchor{358}
-@section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads})
-
-
-@geindex GNAT.Encode_UTF8_String (g-enutst.ads)
-
-@geindex Encoding strings
-
-@geindex Encoding UTF-8 strings
-
-@geindex UTF-8 string encoding
-
-@geindex Wide character encoding
-
-@geindex UTF-8
-
-@geindex Unicode
-
-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 gnat-exception-actions-g-excact-ads}@anchor{359}@anchor{gnat_rm/the_gnat_library id67}@anchor{35a}
-@section @code{GNAT.Exception_Actions} (@code{g-excact.ads})
-
-
-@geindex GNAT.Exception_Actions (g-excact.ads)
-
-@geindex Exception actions
-
-Provides callbacks when an exception is raised. Callbacks can be registered
-for specific exceptions, or when any exception is raised. This
-can be used for instance to force a core dump to ease debugging.
-
-@node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{35b}@anchor{gnat_rm/the_gnat_library id68}@anchor{35c}
-@section @code{GNAT.Exception_Traces} (@code{g-exctra.ads})
-
-
-@geindex GNAT.Exception_Traces (g-exctra.ads)
-
-@geindex Exception traces
-
-@geindex Debugging
-
-Provides an interface allowing to control automatic output upon exception
-occurrences.
-
-@node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{35d}@anchor{gnat_rm/the_gnat_library id69}@anchor{35e}
-@section @code{GNAT.Exceptions} (@code{g-except.ads})
-
-
-@geindex GNAT.Exceptions (g-except.ads)
-
-@geindex Exceptions
-@geindex Pure
-
-@geindex Pure packages
-@geindex exceptions
-
-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 @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
-@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-except ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{35f}@anchor{gnat_rm/the_gnat_library id70}@anchor{360}
-@section @code{GNAT.Expect} (@code{g-expect.ads})
-
-
-@geindex GNAT.Expect (g-expect.ads)
-
-Provides a set of subprograms similar to what is available
-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 @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{361}@anchor{gnat_rm/the_gnat_library id71}@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 @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 gnat-float-control-g-flocon-ads}@anchor{363}@anchor{gnat_rm/the_gnat_library id72}@anchor{364}
-@section @code{GNAT.Float_Control} (@code{g-flocon.ads})
-
-
-@geindex GNAT.Float_Control (g-flocon.ads)
-
-@geindex Floating-Point Processor
-
-Provides an interface for resetting the floating-point processor into the
-mode required for correct semantic operation in Ada.  Some third party
-library calls may cause this mode to be modified, and the Reset procedure
-in this package can be used to reestablish the required mode.
-
-@node GNAT Formatted_String g-forstr ads,GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Float_Control g-flocon ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{365}@anchor{gnat_rm/the_gnat_library id73}@anchor{366}
-@section @code{GNAT.Formatted_String} (@code{g-forstr.ads})
-
-
-@geindex GNAT.Formatted_String (g-forstr.ads)
-
-@geindex Formatted String
-
-Provides support for C/C++ printf() formatted strings. The format is
-copied from the printf() routine and should therefore gives identical
-output. Some generic routines are provided to be able to use types
-derived from Integer, Float or enumerations as values for the
-formatted string.
-
-@node GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Heap_Sort g-heasor ads,GNAT Formatted_String g-forstr ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-generic-fast-math-functions-g-gfmafu-ads}@anchor{367}@anchor{gnat_rm/the_gnat_library id74}@anchor{368}
-@section @code{GNAT.Generic_Fast_Math_Functions} (@code{g-gfmafu.ads})
-
-
-@geindex GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads)
-
-@geindex Mathematical functions
-
-Provides direct access to the underlying implementation of the common
-mathematical functions, generally from the system mathematical library.
-This differs from @code{Ada.Numerics.Generic_Elementary_Functions} in that
-the implementation may deviate from the semantics specified for these
-functions in the Reference Manual, for example @code{Numerics.Argument_Error}
-is not raised. On selected platforms, some of these functions may also
-have a vector implementation that can be automatically used by the
-compiler when auto-vectorization is enabled.
-
-@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Generic_Fast_Math_Functions g-gfmafu ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{369}@anchor{gnat_rm/the_gnat_library id75}@anchor{36a}
-@section @code{GNAT.Heap_Sort} (@code{g-heasor.ads})
-
-
-@geindex GNAT.Heap_Sort (g-heasor.ads)
-
-@geindex Sorting
-
-Provides a general implementation of heap sort usable for sorting arbitrary
-data items. Exchange 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.
-
-@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 gnat-heap-sort-a-g-hesora-ads}@anchor{36b}@anchor{gnat_rm/the_gnat_library id76}@anchor{36c}
-@section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads})
-
-
-@geindex GNAT.Heap_Sort_A (g-hesora.ads)
-
-@geindex Sorting
-
-Provides a general implementation of heap sort usable for sorting arbitrary
-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 @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 gnat-heap-sort-g-g-hesorg-ads}@anchor{36d}@anchor{gnat_rm/the_gnat_library id77}@anchor{36e}
-@section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads})
-
-
-@geindex GNAT.Heap_Sort_G (g-hesorg.ads)
-
-@geindex Sorting
-
-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 gnat-htable-g-htable-ads}@anchor{36f}@anchor{gnat_rm/the_gnat_library id78}@anchor{370}
-@section @code{GNAT.HTable} (@code{g-htable.ads})
-
-
-@geindex GNAT.HTable (g-htable.ads)
-
-@geindex Hash tables
-
-A generic implementation of hash tables that can be used to hash arbitrary
-data.  Provides two approaches, one a simple static approach, and the other
-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 gnat-io-g-io-ads}@anchor{371}@anchor{gnat_rm/the_gnat_library id79}@anchor{372}
-@section @code{GNAT.IO} (@code{g-io.ads})
-
-
-@geindex GNAT.IO (g-io.ads)
-
-@geindex Simple I/O
-
-@geindex Input/Output facilities
-
-A simple preelaborable input-output package that provides a subset of
-simple Text_IO functions for reading characters and strings from
-Standard_Input, and writing characters, strings and integers to either
-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 gnat-io-aux-g-io-aux-ads}@anchor{373}@anchor{gnat_rm/the_gnat_library id80}@anchor{374}
-@section @code{GNAT.IO_Aux} (@code{g-io_aux.ads})
-
-
-@geindex GNAT.IO_Aux (g-io_aux.ads)
-
-@geindex Text_IO
-
-@geindex Input/Output facilities
-
-Provides some auxiliary functions for use with Text_IO, including a test
-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{375}@anchor{gnat_rm/the_gnat_library id81}@anchor{376}
-@section @code{GNAT.Lock_Files} (@code{g-locfil.ads})
-
-
-@geindex GNAT.Lock_Files (g-locfil.ads)
-
-@geindex File locking
-
-@geindex Locking using files
-
-Provides a general interface for using files as locks.  Can be used for
-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 gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{377}@anchor{gnat_rm/the_gnat_library id82}@anchor{378}
-@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 @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 gnat-mbbs-float-random-g-mbflra-ads}@anchor{379}@anchor{gnat_rm/the_gnat_library id83}@anchor{37a}
-@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 @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 gnat-md5-g-md5-ads}@anchor{37b}@anchor{gnat_rm/the_gnat_library id84}@anchor{37c}
-@section @code{GNAT.MD5} (@code{g-md5.ads})
-
-
-@geindex GNAT.MD5 (g-md5.ads)
-
-@geindex Message Digest MD5
-
-Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and
-the HMAC-MD5 message authentication function as described in RFC 2104 and
-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 gnat-memory-dump-g-memdum-ads}@anchor{37d}@anchor{gnat_rm/the_gnat_library id85}@anchor{37e}
-@section @code{GNAT.Memory_Dump} (@code{g-memdum.ads})
-
-
-@geindex GNAT.Memory_Dump (g-memdum.ads)
-
-@geindex Dump Memory
-
-Provides a convenient routine for dumping raw memory to either the
-standard output or standard error files. Uses GNAT.IO for actual
-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 gnat-most-recent-exception-g-moreex-ads}@anchor{37f}@anchor{gnat_rm/the_gnat_library id86}@anchor{380}
-@section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads})
-
-
-@geindex GNAT.Most_Recent_Exception (g-moreex.ads)
-
-@geindex Exception
-@geindex obtaining most recent
-
-Provides access to the most recently raised exception.  Can be used for
-various logging purposes, including duplicating functionality of some
-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 gnat-os-lib-g-os-lib-ads}@anchor{381}@anchor{gnat_rm/the_gnat_library id87}@anchor{382}
-@section @code{GNAT.OS_Lib} (@code{g-os_lib.ads})
-
-
-@geindex GNAT.OS_Lib (g-os_lib.ads)
-
-@geindex Operating System interface
-
-@geindex Spawn capability
-
-Provides a range of target independent operating system interface functions,
-including time/date management, file operations, subprocess management,
-including a portable spawn procedure, and access to environment variables
-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{383}@anchor{gnat_rm/the_gnat_library id88}@anchor{384}
-@section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads})
-
-
-@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads)
-
-@geindex Hash functions
-
-Provides a generator of static minimal perfect hash functions. No
-collisions occur and each item can be retrieved from the table in one
-probe (perfect property). The hash table size corresponds to the exact
-size of the key set and no larger (minimal property). The key set has to
-be know in advance (static property). The hash functions are also order
-preserving. If w2 is inserted after w1 in the generator, their
-hashcode are in the same order. These hashing functions are very
-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{385}@anchor{gnat_rm/the_gnat_library id89}@anchor{386}
-@section @code{GNAT.Random_Numbers} (@code{g-rannum.ads})
-
-
-@geindex GNAT.Random_Numbers (g-rannum.ads)
-
-@geindex Random number generation
-
-Provides random number capabilities which extend those available in the
-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{25c}@anchor{gnat_rm/the_gnat_library id90}@anchor{387}
-@section @code{GNAT.Regexp} (@code{g-regexp.ads})
-
-
-@geindex GNAT.Regexp (g-regexp.ads)
-
-@geindex Regular expressions
-
-@geindex Pattern matching
-
-A simple implementation of regular expressions, using a subset of regular
-expression syntax copied from familiar Unix style utilities.  This is the
-simplest of the three pattern matching packages provided, and is particularly
-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 gnat-registry-g-regist-ads}@anchor{388}@anchor{gnat_rm/the_gnat_library id91}@anchor{389}
-@section @code{GNAT.Registry} (@code{g-regist.ads})
-
-
-@geindex GNAT.Registry (g-regist.ads)
-
-@geindex Windows Registry
-
-This is a high level binding to the Windows registry.  It is possible to
-do simple things like reading a key value, creating a new key.  For full
-registry API, but at a lower level of abstraction, refer to the Win32.Winreg
-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{38a}@anchor{gnat_rm/the_gnat_library id92}@anchor{38b}
-@section @code{GNAT.Regpat} (@code{g-regpat.ads})
-
-
-@geindex GNAT.Regpat (g-regpat.ads)
-
-@geindex Regular expressions
-
-@geindex Pattern matching
-
-A complete implementation of Unix-style regular expression matching, copied
-from the original V7 style regular expression library written in C by
-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 gnat-rewrite-data-g-rewdat-ads}@anchor{38c}@anchor{gnat_rm/the_gnat_library id93}@anchor{38d}
-@section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads})
-
-
-@geindex GNAT.Rewrite_Data (g-rewdat.ads)
-
-@geindex Rewrite data
-
-A unit to rewrite on-the-fly string occurrences in a stream of
-data. The implementation has a very minimal memory footprint as the
-full content to be processed is not loaded into memory all at once. This makes
-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{38e}@anchor{gnat_rm/the_gnat_library id94}@anchor{38f}
-@section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads})
-
-
-@geindex GNAT.Secondary_Stack_Info (g-sestin.ads)
-
-@geindex Secondary Stack Info
-
-Provide the capability to query the high water mark of the current task’s
-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 gnat-semaphores-g-semaph-ads}@anchor{390}@anchor{gnat_rm/the_gnat_library id95}@anchor{391}
-@section @code{GNAT.Semaphores} (@code{g-semaph.ads})
-
-
-@geindex GNAT.Semaphores (g-semaph.ads)
-
-@geindex Semaphores
-
-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{392}@anchor{gnat_rm/the_gnat_library id96}@anchor{393}
-@section @code{GNAT.Serial_Communications} (@code{g-sercom.ads})
-
-
-@geindex GNAT.Serial_Communications (g-sercom.ads)
-
-@geindex Serial_Communications
-
-Provides a simple interface to send and receive data over a serial
-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{394}@anchor{gnat_rm/the_gnat_library id97}@anchor{395}
-@section @code{GNAT.SHA1} (@code{g-sha1.ads})
-
-
-@geindex GNAT.SHA1 (g-sha1.ads)
-
-@geindex Secure Hash Algorithm SHA-1
-
-Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3
-and RFC 3174, and the HMAC-SHA1 message authentication function as described
-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 gnat-sha224-g-sha224-ads}@anchor{396}@anchor{gnat_rm/the_gnat_library id98}@anchor{397}
-@section @code{GNAT.SHA224} (@code{g-sha224.ads})
-
-
-@geindex GNAT.SHA224 (g-sha224.ads)
-
-@geindex Secure Hash Algorithm SHA-224
-
-Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3,
-and the HMAC-SHA224 message authentication function as described
-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 gnat-sha256-g-sha256-ads}@anchor{398}@anchor{gnat_rm/the_gnat_library id99}@anchor{399}
-@section @code{GNAT.SHA256} (@code{g-sha256.ads})
-
-
-@geindex GNAT.SHA256 (g-sha256.ads)
-
-@geindex Secure Hash Algorithm SHA-256
-
-Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3,
-and the HMAC-SHA256 message authentication function as described
-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 gnat-sha384-g-sha384-ads}@anchor{39a}@anchor{gnat_rm/the_gnat_library id100}@anchor{39b}
-@section @code{GNAT.SHA384} (@code{g-sha384.ads})
-
-
-@geindex GNAT.SHA384 (g-sha384.ads)
-
-@geindex Secure Hash Algorithm SHA-384
-
-Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3,
-and the HMAC-SHA384 message authentication function as described
-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{39c}@anchor{gnat_rm/the_gnat_library id101}@anchor{39d}
-@section @code{GNAT.SHA512} (@code{g-sha512.ads})
-
-
-@geindex GNAT.SHA512 (g-sha512.ads)
-
-@geindex Secure Hash Algorithm SHA-512
-
-Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3,
-and the HMAC-SHA512 message authentication function as described
-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{39e}@anchor{gnat_rm/the_gnat_library id102}@anchor{39f}
-@section @code{GNAT.Signals} (@code{g-signal.ads})
-
-
-@geindex GNAT.Signals (g-signal.ads)
-
-@geindex Signals
-
-Provides the ability to manipulate the blocked status of signals on supported
-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{3a0}@anchor{gnat_rm/the_gnat_library id103}@anchor{3a1}
-@section @code{GNAT.Sockets} (@code{g-socket.ads})
-
-
-@geindex GNAT.Sockets (g-socket.ads)
-
-@geindex Sockets
-
-A high level and portable interface to develop sockets based applications.
-This package is based on the sockets thin binding found in
-@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{3a2}@anchor{gnat_rm/the_gnat_library id104}@anchor{3a3}
-@section @code{GNAT.Source_Info} (@code{g-souinf.ads})
-
-
-@geindex GNAT.Source_Info (g-souinf.ads)
-
-@geindex Source Information
-
-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 @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{3a4}@anchor{gnat_rm/the_gnat_library id105}@anchor{3a5}
-@section @code{GNAT.Spelling_Checker} (@code{g-speche.ads})
-
-
-@geindex GNAT.Spelling_Checker (g-speche.ads)
-
-@geindex Spell checking
-
-Provides a function for determining whether one string is a plausible
-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 gnat-spelling-checker-generic-g-spchge-ads}@anchor{3a6}@anchor{gnat_rm/the_gnat_library id106}@anchor{3a7}
-@section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads})
-
-
-@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads)
-
-@geindex Spell checking
-
-Provides a generic function that can be instantiated with a string type for
-determining whether one string is a plausible near misspelling of another
-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 gnat-spitbol-patterns-g-spipat-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id107}@anchor{3a9}
-@section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads})
-
-
-@geindex GNAT.Spitbol.Patterns (g-spipat.ads)
-
-@geindex SPITBOL pattern matching
-
-@geindex Pattern matching
-
-A complete implementation of SNOBOL4 style pattern matching.  This is the
-most elaborate of the pattern matching packages provided.  It fully duplicates
-the SNOBOL4 dynamic pattern construction and matching capabilities, using the
-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 gnat-spitbol-g-spitbo-ads}@anchor{3aa}@anchor{gnat_rm/the_gnat_library id108}@anchor{3ab}
-@section @code{GNAT.Spitbol} (@code{g-spitbo.ads})
-
-
-@geindex GNAT.Spitbol (g-spitbo.ads)
-
-@geindex SPITBOL interface
-
-The top level package of the collection of SPITBOL-style functionality, this
-package provides basic SNOBOL4 string manipulation functions, such as
-Pad, Reverse, Trim, Substr capability, as well as a generic table function
-useful for constructing arbitrary mappings from strings in the style of
-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 gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id109}@anchor{3ad}
-@section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads})
-
-
-@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
-
-@geindex Sets of strings
-
-@geindex SPITBOL Tables
-
-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 gnat-spitbol-table-integer-g-sptain-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id110}@anchor{3af}
-@section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads})
-
-
-@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads)
-
-@geindex Integer maps
-
-@geindex Maps
-
-@geindex SPITBOL Tables
-
-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 gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3b0}@anchor{gnat_rm/the_gnat_library id111}@anchor{3b1}
-@section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads})
-
-
-@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads)
-
-@geindex String maps
-
-@geindex Maps
-
-@geindex SPITBOL Tables
-
-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 gnat-sse-g-sse-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id112}@anchor{3b3}
-@section @code{GNAT.SSE} (@code{g-sse.ads})
-
-
-@geindex GNAT.SSE (g-sse.ads)
-
-Root of a set of units aimed at offering Ada bindings to a subset of
-the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of
-targets.  It exposes vector component types together with a general
-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{3b4}@anchor{gnat_rm/the_gnat_library id113}@anchor{3b5}
-@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{3b6}@anchor{gnat_rm/the_gnat_library id114}@anchor{3b7}
-@section @code{GNAT.String_Hash} (@code{g-strhas.ads})
-
-
-@geindex GNAT.String_Hash (g-strhas.ads)
-
-@geindex Hash functions
-
-Provides a generic hash function working on arrays of scalars. Both the scalar
-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 gnat-strings-g-string-ads}@anchor{3b8}@anchor{gnat_rm/the_gnat_library id115}@anchor{3b9}
-@section @code{GNAT.Strings} (@code{g-string.ads})
-
-
-@geindex GNAT.Strings (g-string.ads)
-
-Common String access types and related subprograms. Basically it
-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{3ba}@anchor{gnat_rm/the_gnat_library id116}@anchor{3bb}
-@section @code{GNAT.String_Split} (@code{g-strspl.ads})
-
-
-@geindex GNAT.String_Split (g-strspl.ads)
-
-@geindex String splitter
-
-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
-@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{3bc}@anchor{gnat_rm/the_gnat_library id117}@anchor{3bd}
-@section @code{GNAT.Table} (@code{g-table.ads})
-
-
-@geindex GNAT.Table (g-table.ads)
-
-@geindex Table implementation
-
-@geindex Arrays
-@geindex extendable
-
-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 @code{GNAT.Dynamic_Tables},
-except that this package declares a single instance of the table type,
-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{3be}@anchor{gnat_rm/the_gnat_library id118}@anchor{3bf}
-@section @code{GNAT.Task_Lock} (@code{g-tasloc.ads})
-
-
-@geindex GNAT.Task_Lock (g-tasloc.ads)
-
-@geindex Task synchronization
-
-@geindex Task locking
-
-@geindex Locking
-
-A very simple facility for locking and unlocking sections of code using a
-single global task lock.  Appropriate for use in situations where contention
-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{3c0}@anchor{gnat_rm/the_gnat_library id119}@anchor{3c1}
-@section @code{GNAT.Time_Stamp} (@code{g-timsta.ads})
-
-
-@geindex GNAT.Time_Stamp (g-timsta.ads)
-
-@geindex Time stamp
-
-@geindex Current time
-
-Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that
-represents the current date and time in ISO 8601 format. This is a very simple
-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{3c2}@anchor{gnat_rm/the_gnat_library id120}@anchor{3c3}
-@section @code{GNAT.Threads} (@code{g-thread.ads})
-
-
-@geindex GNAT.Threads (g-thread.ads)
-
-@geindex Foreign threads
-
-@geindex Threads
-@geindex foreign
-
-Provides facilities for dealing with foreign threads which need to be known
-by the GNAT run-time system. Consult the documentation of this package for
-further details if your program has threads that are created by a non-Ada
-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 gnat-traceback-g-traceb-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id121}@anchor{3c5}
-@section @code{GNAT.Traceback} (@code{g-traceb.ads})
-
-
-@geindex GNAT.Traceback (g-traceb.ads)
-
-@geindex Trace back facilities
-
-Provides a facility for obtaining non-symbolic traceback information, useful
-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{3c6}@anchor{gnat_rm/the_gnat_library id122}@anchor{3c7}
-@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 gnat-utf-32-g-table-ads}@anchor{3c8}@anchor{gnat_rm/the_gnat_library id123}@anchor{3c9}
-@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
-@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
-lower case to upper case fold routine corresponding to
-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{3ca}@anchor{gnat_rm/the_gnat_library id124}@anchor{3cb}
-@section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads})
-
-
-@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads)
-
-@geindex Spell checking
-
-Provides a function for determining whether one wide wide string is a plausible
-near misspelling of another wide wide string, where the strings are represented
-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{3cc}@anchor{gnat_rm/the_gnat_library id125}@anchor{3cd}
-@section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads})
-
-
-@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads)
-
-@geindex Spell checking
-
-Provides a function for determining whether one wide string is a plausible
-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{3ce}@anchor{gnat_rm/the_gnat_library id126}@anchor{3cf}
-@section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads})
-
-
-@geindex GNAT.Wide_String_Split (g-wistsp.ads)
-
-@geindex Wide_String splitter
-
-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
-@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{3d0}@anchor{gnat_rm/the_gnat_library id127}@anchor{3d1}
-@section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads})
-
-
-@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
-
-@geindex Spell checking
-
-Provides a function for determining whether one wide wide string is a plausible
-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{3d2}@anchor{gnat_rm/the_gnat_library id128}@anchor{3d3}
-@section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads})
-
-
-@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads)
-
-@geindex Wide_Wide_String splitter
-
-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
-@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 id129}@anchor{3d4}@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3d5}
-@section @code{Interfaces.C.Extensions} (@code{i-cexten.ads})
-
-
-@geindex Interfaces.C.Extensions (i-cexten.ads)
-
-This package contains additional C-related definitions, intended
-for use with either manually or automatically generated bindings
-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 id130}@anchor{3d6}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3d7}
-@section @code{Interfaces.C.Streams} (@code{i-cstrea.ads})
-
-
-@geindex Interfaces.C.Streams (i-cstrea.ads)
-
-@geindex C streams
-@geindex interfacing
-
-This package is a binding for the most commonly used operations
-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 id131}@anchor{3d8}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3d9}
-@section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads})
-
-
-@geindex Interfaces.Packed_Decimal (i-pacdec.ads)
-
-@geindex IBM Packed Format
-
-@geindex Packed Decimal
-
-This package provides a set of routines for conversions to and
-from a packed decimal format compatible with that used on IBM
-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 id132}@anchor{3da}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3db}
-@section @code{Interfaces.VxWorks} (@code{i-vxwork.ads})
-
-
-@geindex Interfaces.VxWorks (i-vxwork.ads)
-
-@geindex Interfacing to VxWorks
-
-@geindex VxWorks
-@geindex interfacing
-
-This package provides a limited binding to the VxWorks API.
-In particular, it interfaces with the
-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 id133}@anchor{3dc}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3dd}
-@section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads})
-
-
-@geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads)
-
-@geindex Interfacing to VxWorks
-
-@geindex VxWorks
-@geindex interfacing
-
-This package provides a way for users to replace the use of
-intConnect() with a custom routine for installing interrupt
-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 id134}@anchor{3de}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3df}
-@section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads})
-
-
-@geindex Interfaces.VxWorks.IO (i-vxwoio.ads)
-
-@geindex Interfacing to VxWorks' I/O
-
-@geindex VxWorks
-@geindex I/O interfacing
-
-@geindex VxWorks
-@geindex Get_Immediate
-
-@geindex Get_Immediate
-@geindex VxWorks
-
-This package provides a binding to the ioctl (IO/Control)
-function of VxWorks, defining a set of option values and
-function codes. A particular use of this package is
-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 id135}@anchor{3e0}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3e1}
-@section @code{System.Address_Image} (@code{s-addima.ads})
-
-
-@geindex System.Address_Image (s-addima.ads)
-
-@geindex Address image
-
-@geindex Image
-@geindex of an address
-
-This function provides a useful debugging
-function that gives an (implementation dependent)
-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 id136}@anchor{3e2}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3e3}
-@section @code{System.Assertions} (@code{s-assert.ads})
-
-
-@geindex System.Assertions (s-assert.ads)
-
-@geindex Assertions
-
-@geindex Assert_Failure
-@geindex exception
-
-This package provides the declaration of the exception raised
-by an run-time assertion failure, as well as the routine that
-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 id137}@anchor{3e4}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3e5}
-@section @code{System.Atomic_Counters} (@code{s-atocou.ads})
-
-
-@geindex System.Atomic_Counters (s-atocou.ads)
-
-This package provides the declaration of an atomic counter type,
-together with efficient routines (using hardware
-synchronization primitives) for incrementing, decrementing,
-and testing of these counters. This package is implemented
-on most targets, including all Alpha, AARCH64, ARM, ia64, PowerPC, SPARC V9,
-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 id138}@anchor{3e6}@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3e7}
-@section @code{System.Memory} (@code{s-memory.ads})
-
-
-@geindex System.Memory (s-memory.ads)
-
-@geindex Memory allocation
-
-This package provides the interface to the low level routines used
-by the generated code for allocation and freeing storage for the
-default storage pool (analogous to the C routines malloc and free).
-It also provides a reallocation interface analogous to the C routine
-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 @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 id139}@anchor{3e8}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3e9}
-@section @code{System.Multiprocessors} (@code{s-multip.ads})
-
-
-@geindex System.Multiprocessors (s-multip.ads)
-
-@geindex Multiprocessor interface
-
-This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but
-in GNAT we also make it available in Ada 95 and Ada 2005 (where it is
-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 id140}@anchor{3ea}@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3eb}
-@section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads})
-
-
-@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads)
-
-@geindex Multiprocessor interface
-
-This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but
-in GNAT we also make it available in Ada 95 and Ada 2005 (where it is
-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 id141}@anchor{3ec}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3ed}
-@section @code{System.Partition_Interface} (@code{s-parint.ads})
-
-
-@geindex System.Partition_Interface (s-parint.ads)
-
-@geindex Partition interfacing functions
-
-This package provides facilities for partition interfacing.  It
-is used primarily in a distribution context when using Annex E
-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 id142}@anchor{3ee}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3ef}
-@section @code{System.Pool_Global} (@code{s-pooglo.ads})
-
-
-@geindex System.Pool_Global (s-pooglo.ads)
-
-@geindex Storage pool
-@geindex global
-
-@geindex Global storage pool
-
-This package provides a storage pool that is equivalent to the default
-storage pool used for access types for which no pool is specifically
-declared. It uses malloc/free to allocate/free and does not attempt to
-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 id143}@anchor{3f0}@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3f1}
-@section @code{System.Pool_Local} (@code{s-pooloc.ads})
-
-
-@geindex System.Pool_Local (s-pooloc.ads)
-
-@geindex Storage pool
-@geindex local
-
-@geindex Local storage pool
-
-This package provides a storage pool that is intended for use with locally
-defined access types. It uses malloc/free for allocate/free, and maintains
-a list of allocated blocks, so that all storage allocated for the pool can
-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 id144}@anchor{3f2}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3f3}
-@section @code{System.Restrictions} (@code{s-restri.ads})
-
-
-@geindex System.Restrictions (s-restri.ads)
-
-@geindex Run-time restrictions access
-
-This package provides facilities for accessing at run time
-the status of restrictions specified at compile time for
-the partition. Information is available both with regard
-to actual restrictions specified, and with regard to
-compiler determined information on which restrictions
-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 id145}@anchor{3f4}@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3f5}
-@section @code{System.Rident} (@code{s-rident.ads})
-
-
-@geindex System.Rident (s-rident.ads)
-
-@geindex Restrictions definitions
-
-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 @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 id146}@anchor{3f6}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{3f7}
-@section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads})
-
-
-@geindex System.Strings.Stream_Ops (s-ststop.ads)
-
-@geindex Stream operations
-
-@geindex String stream operations
-
-This package provides a set of stream subprograms for standard string types.
-It is intended primarily to support implicit use of such subprograms when
-stream attributes are applied to string types, but the subprograms in this
-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 id147}@anchor{3f8}@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{3f9}
-@section @code{System.Unsigned_Types} (@code{s-unstyp.ads})
-
-
-@geindex System.Unsigned_Types (s-unstyp.ads)
-
-This package contains definitions of standard unsigned types that
-correspond in size to the standard signed types declared in Standard,
-and (unlike the types in Interfaces) have corresponding names. It
-also contains some related definitions for other specialized types
-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 id148}@anchor{3fa}@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{3fb}
-@section @code{System.Wch_Cnv} (@code{s-wchcnv.ads})
-
-
-@geindex System.Wch_Cnv (s-wchcnv.ads)
-
-@geindex Wide Character
-@geindex Representation
-
-@geindex Wide String
-@geindex Conversion
-
-@geindex Representation of wide characters
-
-This package provides routines for converting between
-wide and wide wide characters and a representation as a value of type
-@code{Standard.String}, using a specified wide character
-encoding method.  It uses definitions in
-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 id149}@anchor{3fc}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{3fd}
-@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 @code{System.Wch_Cnv}.
-
-@node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top
-@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{3fe}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{3ff}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}
-@chapter Interfacing to Other Languages
-
-
-The facilities in Annex B of the Ada Reference Manual are fully
-implemented in GNAT, and in addition, a full interface to C++ is
-provided.
-
-@menu
-* Interfacing to C:: 
-* Interfacing to C++:: 
-* Interfacing to COBOL:: 
-* Interfacing to Fortran:: 
-* Interfacing to non-GNAT Ada code:: 
-
-@end menu
-
-@node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages
-@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{400}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{401}
-@section Interfacing to C
-
-
-Interfacing to C with GNAT can use one of two approaches:
-
-
-@itemize *
-
-@item 
-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
-other compilers, but will work on all GNAT compilers, which guarantee
-correspondence between the C and Ada types.
-@end itemize
-
-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.
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@headitem
-
-Ada Type
-
-@tab
-
-C Type
-
-@item
-
-@code{Integer}
-
-@tab
-
-@code{int}
-
-@item
-
-@code{Short_Integer}
-
-@tab
-
-@code{short}
-
-@item
-
-@code{Short_Short_Integer}
-
-@tab
-
-@code{signed char}
-
-@item
-
-@code{Long_Integer}
-
-@tab
-
-@code{long}
-
-@item
-
-@code{Long_Long_Integer}
-
-@tab
-
-@code{long long}
-
-@item
-
-@code{Short_Float}
-
-@tab
-
-@code{float}
-
-@item
-
-@code{Float}
-
-@tab
-
-@code{float}
-
-@item
-
-@code{Long_Float}
-
-@tab
-
-@code{double}
-
-@item
-
-@code{Long_Long_Float}
-
-@tab
-
-This is the longest floating-point type supported by the hardware.
-
-@end multitable
-
-
-Additionally, there are the following general correspondences between Ada
-and C types:
-
-
-@itemize *
-
-@item 
-Ada enumeration types map to C enumeration types directly if pragma
-@code{Convention C} is specified, which causes them to have a length of
-32 bits, except for boolean types which map to C99 @code{bool} and for
-which the length is 8 bits.
-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 
-Ada access types map to C pointers, except for the case of pointers to
-unconstrained types in Ada, which have no direct C equivalent.
-
-@item 
-Ada arrays map directly to C arrays.
-
-@item 
-Ada records map directly to C structures.
-
-@item 
-Packed Ada records map to C structures where all members are bit fields
-of the length corresponding to the @code{type'Size} value in Ada.
-@end itemize
-
-@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages
-@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{47}@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{402}
-@section Interfacing to C++
-
-
-The interface to C++ makes use of the following pragmas, which are
-primarily intended to be constructed automatically using a binding generator
-tool, although it is possible to construct them by hand.
-
-Using these pragmas it is possible to achieve complete
-inter-operability between Ada tagged types and C++ class definitions.
-See @ref{7,,Implementation Defined Pragmas}, for more details.
-
-
-@table @asis
-
-@item @code{pragma CPP_Class ([Entity =>] @var{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 @code{CPP_Class} is currently obsolete. It is supported
-for backward compatibility but its functionality is available
-using pragma @code{Import} with @code{Convention} = @code{CPP}.
-
-@item @code{pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME})}
-
-This pragma identifies an imported function (imported in the usual way
-with pragma @code{Import}) as corresponding to a C++ constructor.
-@end table
-
-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 @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
-@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.
-
-It is also possible to import a C++ exception using the following syntax:
-
-@example
-LOCAL_NAME : exception;
-pragma Import (Cpp,
-  [Entity =>] LOCAL_NAME,
-  [External_Name =>] static_string_EXPRESSION);
-@end example
-
-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{403}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{404}
-@section Interfacing to COBOL
-
-
-Interfacing to COBOL is achieved as described in section B.4 of
-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{405}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{406}
-@section Interfacing to Fortran
-
-
-Interfacing to Fortran is achieved as described in section B.5 of the
-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 id7}@anchor{407}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{408}
-@section Interfacing to non-GNAT Ada code
-
-
-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.
-
-If arguments types are kept simple, and if the foreign compiler generally
-follows system calling conventions, then it may be possible to integrate
-files compiled by other Ada compilers, provided that the elaboration
-issues are adequately addressed (for example by eliminating the
-need for any load time elaboration).
-
-In particular, GNAT running on VMS is designed to
-be highly compatible with the DEC Ada 83 compiler, so this is one
-case in which it is possible to import foreign units of this type,
-provided that the data items passed are restricted to simple scalar
-values or simple record types without variants, or simple array
-types with fixed bounds.
-
-@node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top
-@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{409}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{40a}@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}
-@chapter Specialized Needs Annexes
-
-
-Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not
-required in all implementations.  However, as described in this chapter,
-GNAT implements all of these annexes:
-
-
-@table @asis
-
-@item `Systems Programming (Annex C)'
-
-The Systems Programming Annex is fully implemented.
-
-@item `Real-Time Systems (Annex D)'
-
-The Real-Time Systems Annex is fully implemented.
-
-@item `Distributed Systems (Annex E)'
-
-Stub generation is fully implemented in the GNAT compiler.  In addition,
-a complete compatible PCS is available as part of the GLADE system,
-a separate product.  When the two
-products are used in conjunction, this annex is fully implemented.
-
-@item `Information Systems (Annex F)'
-
-The Information Systems annex is fully implemented.
-
-@item `Numerics (Annex G)'
-
-The Numerics Annex is fully implemented.
-
-@item `Safety and Security / High-Integrity Systems (Annex H)'
-
-The Safety and Security Annex (termed the High-Integrity Systems Annex
-in Ada 2005) is fully implemented.
-@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 doc}@anchor{40b}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{40c}@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13}
-@chapter Implementation of Specific Ada Features
-
-
-This chapter describes the GNAT implementation of several Ada language
-facilities.
-
-@menu
-* Machine Code Insertions:: 
-* GNAT Implementation of Tasking:: 
-* GNAT Implementation of Shared Passive Packages:: 
-* Code Generation for Array Aggregates:: 
-* The Size of Discriminated Records with Default Discriminants:: 
-* Image Values For Nonscalar Types:: 
-* Strict Conformance to the Ada Reference Manual:: 
-
-@end menu
-
-@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features
-@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{40d}@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{166}
-@section Machine Code Insertions
-
-
-@geindex Machine Code insertions
-
-Package @code{Machine_Code} provides machine code support as described
-in the Ada Reference Manual in two separate forms:
-
-
-@itemize *
-
-@item 
-Machine code statements, consisting of qualified expressions that
-fit the requirements of RM section 13.8.
-
-@item 
-An intrinsic callable procedure, providing an alternative mechanism of
-including machine instructions in a subprogram.
-@end itemize
-
-The two features are similar, and both are closely related to the mechanism
-provided by the asm instruction in the GNU C compiler.  Full understanding
-and use of the facilities in this package requires understanding the asm
-instruction, see the section on Extended Asm in
-@cite{Using_the_GNU_Compiler_Collection_(GCC)}.
-
-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 @code{asm} instruction:
-
-@example
-asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
-@end example
-
-The equivalent can be written for GNAT as:
-
-@example
-Asm ("fsinx %1 %0",
-     My_Float'Asm_Output ("=f", result),
-     My_Float'Asm_Input  ("f",  angle));
-@end example
-
-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 @code{Asm_Output} attribute reference, or a list of such
-references enclosed in parentheses (technically an array aggregate of
-such references).
-
-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
-constraint (see the section on Constraints in
-@cite{Using_the_GNU_Compiler_Collection_(GCC)})
-for the parameter; e.g., what kind of register is required.  The second
-argument is the variable to be written or updated with 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 @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 @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
-@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 @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,
-(e.g., what kind of register is required).  The second argument is the
-value to be used as the input argument.  The possible values for the
-constraint are the same as those used in the RTL, and are dependent on
-the configuration file used to built the GCC back end.
-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 @code{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 @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 @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
-`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
-used.  See @cite{Using_the_GNU_Compiler_Collection_(GCC)}
-for the full description.
-Generally it is strongly advisable to use Volatile for any ASM statement
-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 @code{asm goto} feature.
-
-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 @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:
-
-@example
-Asm_Insn'(Asm (...));
-Asm_Insn'(Asm_Volatile (...));
-@end example
-
-In accordance with RM rules, such code statements are allowed only
-within subprograms whose entire body consists of such statements.  It is
-not permissible to intermix such statements with other Ada statements.
-
-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 @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:
-
-@example
-ASM_CALL ::= Asm (
-                 [Template =>] static_string_EXPRESSION
-               [,[Outputs  =>] OUTPUT_OPERAND_LIST      ]
-               [,[Inputs   =>] INPUT_OPERAND_LIST       ]
-               [,[Clobber  =>] static_string_EXPRESSION ]
-               [,[Volatile =>] static_boolean_EXPRESSION] )
-
-OUTPUT_OPERAND_LIST ::=
-  [PREFIX.]No_Output_Operands
-| OUTPUT_OPERAND_ATTRIBUTE
-| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@})
-
-OUTPUT_OPERAND_ATTRIBUTE ::=
-  SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
-
-INPUT_OPERAND_LIST ::=
-  [PREFIX.]No_Input_Operands
-| INPUT_OPERAND_ATTRIBUTE
-| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@})
-
-INPUT_OPERAND_ATTRIBUTE ::=
-  SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
-@end example
-
-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
-@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 gnat-implementation-of-tasking}@anchor{40e}@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{40f}
-@section GNAT Implementation of Tasking
-
-
-This chapter outlines the basic GNAT approach to tasking (in particular,
-a multi-layered library for portability) and discusses issues related
-to compliance with the Real-Time Systems Annex.
-
-@menu
-* Mapping Ada Tasks onto the Underlying Kernel Threads:: 
-* Ensuring Compliance with the Real-Time Annex:: 
-* Support for Locking Policies:: 
-
-@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 id4}@anchor{410}@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{411}
-@subsection Mapping Ada Tasks onto the Underlying Kernel Threads
-
-
-GNAT’s run-time support comprises two layers:
-
-
-@itemize *
-
-@item 
-GNARL (GNAT Run-time Layer)
-
-@item 
-GNULL (GNAT Low-level Library)
-@end itemize
-
-In GNAT, Ada’s tasking services rely on a platform and OS independent
-layer known as GNARL.  This code is responsible for implementing the
-correct semantics of Ada’s task creation, rendezvous, protected
-operations etc.
-
-GNARL decomposes Ada’s tasking semantics into simpler lower level
-operations such as create a thread, set the priority of a thread,
-yield, create a lock, lock/unlock, etc.  The spec for these low-level
-operations constitutes GNULLI, the GNULL Interface.  This interface is
-directly inspired from the POSIX real-time API.
-
-If the underlying executive or OS implements the POSIX standard
-faithfully, the GNULL Interface maps as is to the services offered by
-the underlying kernel.  Otherwise, some target dependent glue code maps
-the services offered by the underlying kernel to the semantics expected
-by GNARL.
-
-Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the
-key point is that each Ada task is mapped on a thread in the underlying
-kernel.  For example, in the case of VxWorks, one Ada task = one VxWorks task.
-
-In addition Ada task priorities map onto the underlying thread priorities.
-Mapping Ada tasks onto the underlying kernel threads has several advantages:
-
-
-@itemize *
-
-@item 
-The underlying scheduler is used to schedule the Ada tasks.  This
-makes Ada tasks as efficient as kernel threads from a scheduling
-standpoint.
-
-@item 
-Interaction with code written in C containing threads is eased
-since at the lowest level Ada tasks and C threads map onto the same
-underlying kernel concept.
-
-@item 
-When an Ada task is blocked during I/O the remaining Ada tasks are
-able to proceed.
-
-@item 
-On multiprocessor systems Ada tasks can execute in parallel.
-@end itemize
-
-Some threads libraries offer a mechanism to fork a new process, with the
-child process duplicating the threads from the parent.
-GNAT does not
-support this functionality when the parent contains more than one task.
-
-@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 ensuring-compliance-with-the-real-time-annex}@anchor{412}@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{413}
-@subsection Ensuring Compliance with the Real-Time Annex
-
-
-@geindex Real-Time Systems Annex compliance
-
-Although mapping Ada tasks onto
-the underlying threads has significant advantages, it does create some
-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 @code{FIFO_Within_Priorities}
-scheduling policy states:
-
-@quotation
-
-`When the active priority of a ready task that is not running
-changes, or the setting of its base priority takes effect, the
-task is removed from the ready queue for its old active priority
-and is added at the tail of the ready queue for its new active
-priority, except in the case where the active priority is lowered
-due to the loss of inherited priority, in which case the task is
-added at the head of the ready queue for its new active priority.'
-@end quotation
-
-While most kernels do put tasks at the end of the priority queue when
-a task changes its priority, (which respects the main
-FIFO_Within_Priorities requirement), almost none keep a thread at the
-beginning of its priority queue when its priority drops from the loss
-of inherited priority.
-
-As a result most vendors have provided incomplete Annex D implementations.
-
-The GNAT run-time, has a nice cooperative solution to this problem
-which ensures that accurate FIFO_Within_Priorities semantics are
-respected.
-
-The principle is as follows.  When an Ada task T is about to start
-running, it checks whether some other Ada task R with the same
-priority as T has been suspended due to the loss of priority
-inheritance.  If this is the case, T yields and is placed at the end of
-its priority queue.  When R arrives at the front of the queue it
-executes.
-
-Note that this simple scheme preserves the relative order of the tasks
-that were ready to execute in the priority queue where R has been
-placed at the end.
-
-@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{414}
-@subsection Support for Locking Policies
-
-
-This section specifies which policies specified by pragma Locking_Policy
-are supported on which platforms.
-
-GNAT supports the standard @code{Ceiling_Locking} policy, and the
-implementation defined @code{Inheritance_Locking} and
-@code{Concurrent_Readers_Locking} policies.
-
-@code{Ceiling_Locking} is supported on all platforms if the operating system
-supports it. In particular, @code{Ceiling_Locking} is not supported on
-VxWorks.
-@code{Inheritance_Locking} is supported on
-Linux,
-Darwin (Mac OS X),
-LynxOS 178,
-and VxWorks.
-@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 gnat-implementation-of-shared-passive-packages}@anchor{415}@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{416}
-@section GNAT Implementation of Shared Passive Packages
-
-
-@geindex Shared passive packages
-
-GNAT fully implements the 
-@geindex pragma Shared_Passive
-pragma
-@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
-between separate partitions of a distributed application using the
-features in Annex E.
-
-@geindex Annex E
-
-@geindex Distribution Systems Annex
-
-However, the implementation approach used by GNAT provides for more
-extensive usage as follows:
-
-
-@table @asis
-
-@item `Communication between separate programs'
-
-This allows separate programs to access the data in passive
-partitions, using protected objects for synchronization where
-needed. The only requirement is that the two programs have a
-common shared file system. It is even possible for programs
-running on different machines with different architectures
-(e.g., different endianness) to communicate via the data in
-a passive partition.
-
-@item `Persistence between program runs'
-
-The data in a passive package can persist from one run of a
-program to another, so that a later program sees the final
-values stored by a previous run of the same program.
-@end table
-
-The implementation approach used is to store the data in files. A
-separate stream file is created for each object in the package, and
-an access to an object causes the corresponding file to be read or
-written.
-
-@geindex SHARED_MEMORY_DIRECTORY environment variable
-
-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
-example, if we have the package
-
-@example
-package X is
-  pragma Shared_Passive (X);
-  Y : Integer;
-  Z : Float;
-end X;
-@end example
-
-and the environment variable is set to @code{/stemp/}, then the files created
-will have the names:
-
-@example
-/stemp/x.y
-/stemp/x.z
-@end example
-
-These files are created when a value is initially written to the object, and
-the files are retained until manually deleted. This provides the persistence
-semantics. If no file exists, it means that no partition has assigned a value
-to the variable; in this case the initial value declared in the package
-will be used. This model ensures that there are no issues in synchronizing
-the elaboration process, since elaboration of passive packages elaborates the
-initial values, but does not create the files.
-
-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
-routines, since these are architecture independent.
-
-If active synchronization is required for access to the variables in the
-shared passive package, then as described in the Ada Reference Manual, the
-package may contain protected objects used for this purpose. In this case
-a lock file (whose name is @code{___lock}, with three underscores)
-is created in the shared memory directory.
-
-@geindex ___lock file (for shared passive packages)
-
-This is used to provide the required locking
-semantics for proper protected object synchronization.
-
-@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{417}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{418}
-@section Code Generation for Array Aggregates
-
-
-Aggregates have a rich syntax and allow the user to specify the values of
-complex data structures by means of a single construct.  As a result, the
-code generated for aggregates can be quite complex and involve loops, case
-statements and multiple assignments.  In the simplest cases, however, the
-compiler will recognize aggregates whose components and constraints are
-fully static, and in those cases the compiler will generate little or no
-executable code.  The following is an outline of the code that GNAT generates
-for various aggregate constructs.  For further details, you will find it
-useful to examine the output produced by the -gnatG flag to see the expanded
-source that is input to the code generator.  You may also want to examine
-the assembly code generated at various levels of optimization.
-
-The code generated for aggregates depends on the context, the component values,
-and the type.  In the context of an object declaration the code generated is
-generally simpler than in the case of an assignment.  As a general rule, static
-component values and static subtypes also lead to simpler code.
-
-@menu
-* Static constant aggregates with static bounds:: 
-* Constant aggregates with unconstrained nominal types:: 
-* Aggregates with static bounds:: 
-* Aggregates with nonstatic bounds:: 
-* Aggregates in assignment statements:: 
-
-@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 id8}@anchor{419}@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{41a}
-@subsection Static constant aggregates with static bounds
-
-
-For the declarations:
-
-@example
-type One_Dim is array (1..10) of integer;
-ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
-@end example
-
-GNAT generates no executable code: the constant ar0 is placed in static memory.
-The same is true for constant aggregates with named associations:
-
-@example
-Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
-Cr3 : constant One_Dim := (others => 7777);
-@end example
-
-The same is true for multidimensional constant arrays such as:
-
-@example
-type two_dim is array (1..3, 1..3) of integer;
-Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
-@end example
-
-The same is true for arrays of one-dimensional arrays: the following are
-static:
-
-@example
-type ar1b  is array (1..3) of boolean;
-type ar_ar is array (1..3) of ar1b;
-None  : constant ar1b := (others => false);     --  fully static
-None2 : constant ar_ar := (1..3 => None);       --  fully static
-@end example
-
-However, for multidimensional aggregates with named associations, GNAT will
-generate assignments and loops, even if all associations are static.  The
-following two declarations generate a loop for the first dimension, and
-individual component assignments for the second dimension:
-
-@example
-Zero1: constant two_dim := (1..3 => (1..3 => 0));
-Zero2: constant two_dim := (others => (others => 0));
-@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{41b}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{41c}
-@subsection Constant aggregates with unconstrained nominal types
-
-
-In such cases the aggregate itself establishes the subtype, so that
-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:
-
-@example
-type One_Unc is array (natural range <>) of integer;
-Cr_Unc : constant One_Unc := (12,24,36);
-@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 aggregates-with-static-bounds}@anchor{41d}@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{41e}
-@subsection Aggregates with static bounds
-
-
-In all previous examples the aggregate was the initial (and immutable) value
-of a constant.  If the aggregate initializes a variable, then code is generated
-for it as a combination of individual assignments and loops over the target
-object.  The declarations
-
-@example
-Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
-Cr_Var2 : One_Dim := (others > -1);
-@end example
-
-generate the equivalent of
-
-@example
-Cr_Var1 (1) := 2;
-Cr_Var1 (2) := 3;
-Cr_Var1 (3) := 5;
-Cr_Var1 (4) := 11;
-
-for I in Cr_Var2'range loop
-   Cr_Var2 (I) := -1;
-end loop;
-@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 aggregates-with-nonstatic-bounds}@anchor{41f}@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{420}
-@subsection Aggregates with nonstatic bounds
-
-
-If the bounds of the aggregate are not statically compatible with the bounds
-of the nominal subtype  of the target, then constraint checks have to be
-generated on the bounds.  For a multidimensional array, constraint checks may
-have to be applied to sub-arrays individually, if they do not have statically
-compatible subtypes.
-
-@node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates
-@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{421}@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{422}
-@subsection Aggregates in assignment statements
-
-
-In general, aggregate assignment requires the construction of a temporary,
-and a copy from the temporary to the target of the assignment.  This is because
-it is not always possible to convert the assignment into a series of individual
-component assignments.  For example, consider the simple case:
-
-@example
-A := (A(2), A(1));
-@end example
-
-This cannot be converted into:
-
-@example
-A(1) := A(2);
-A(2) := A(1);
-@end example
-
-So the aggregate has to be built first in a separate location, and then
-copied into the target.  GNAT recognizes simple cases where this intermediate
-step is not required, and the assignments can be performed in place, directly
-into the target.  The following sufficient criteria are applied:
-
-
-@itemize *
-
-@item 
-The bounds of the aggregate are static, and the associations are static.
-
-@item 
-The components of the aggregate are static constants, names of
-simple variables that are not renamings, or expressions not involving
-indexed components whose operands obey these rules.
-@end itemize
-
-If any of these conditions are violated, the aggregate will be built in
-a temporary (created either by the front-end or the code generator) and then
-that temporary will be copied onto the target.
-
-@node The Size of Discriminated Records with Default Discriminants,Image Values For Nonscalar Types,Code Generation for Array Aggregates,Implementation of Specific Ada Features
-@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{423}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{424}
-@section The Size of Discriminated Records with Default Discriminants
-
-
-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:
-
-@example
-type Size is range 1..100;
-
-type Rec (D : Size := 15) is record
-   Name : String (1..D);
-end T;
-
-Word : Rec;
-@end example
-
-Such an object is said to be `unconstrained'.
-The discriminant of the object
-can be modified by a full assignment to the object, as long as it preserves the
-relation between the value of the discriminant, and the value of the components
-that depend on it:
-
-@example
-Word := (3, "yes");
-
-Word := (5, "maybe");
-
-Word := (5, "no"); -- raises Constraint_Error
-@end example
-
-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, @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 @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,
-an Ada compiler should reserve the full size for an unconstrained declared
-object, and place it on the stack.
-
-This maximum size approach
-has been a source of surprise to some users, who expect the default
-values of the discriminants to determine the size reserved for an
-unconstrained object: “If the default is 15, why should the object occupy
-a larger size?”
-The answer, of course, is that the discriminant may be later modified,
-and its full range of values must be taken into account. This is why the
-declaration:
-
-@example
-type Rec (D : Positive := 15) is record
-   Name : String (1..D);
-end record;
-
-Too_Large : Rec;
-@end example
-
-is flagged by the compiler with a warning:
-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 @code{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
-cannot be modified by full assignment. This is because in the presence of
-aliasing all views of the object (which may be manipulated by different tasks,
-say) must be consistent, so it is imperative that the object, once created,
-remain invariant.
-
-@node Image Values For Nonscalar Types,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 id14}@anchor{425}@anchor{gnat_rm/implementation_of_specific_ada_features image-values-for-nonscalar-types}@anchor{426}
-@section Image Values For Nonscalar Types
-
-
-Ada 2022 defines the Image, Wide_Image, and Wide_Wide image attributes
-for nonscalar types; earlier Ada versions defined these attributes only
-for scalar types. Ada RM 4.10 provides some general guidance regarding
-the default implementation of these attributes and the GNAT compiler
-follows that guidance. However, beyond that the precise details of the
-image text generated in these cases are deliberately not documented and are
-subject to change. In particular, users should not rely on formatting details
-(such as spaces or line breaking), record field order, image values for access
-types, image values for types that have ancestor or subcomponent types
-declared in non-Ada2022 code, image values for predefined types, or the
-compiler’s choices regarding the implementation permissions described in
-Ada RM 4.10. This list is not intended to be exhaustive. If more precise
-control of image text is required for some type T, then T’Put_Image should be
-explicitly specified.
-
-@node Strict Conformance to the Ada Reference Manual,,Image Values For Nonscalar Types,Implementation of Specific Ada Features
-@anchor{gnat_rm/implementation_of_specific_ada_features id15}@anchor{427}@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{428}
-@section Strict Conformance to the Ada Reference Manual
-
-
-The dynamic semantics defined by the Ada Reference Manual impose a set of
-run-time checks to be generated. By default, the GNAT compiler will insert many
-run-time checks into the compiled code, including most of those required by the
-Ada Reference Manual. However, there are two checks that are not enabled in
-the default mode for efficiency reasons: checks for access before elaboration
-on subprogram calls, and stack overflow checking (most operating systems do not
-perform this check by default).
-
-Strict conformance to the Ada Reference Manual can be achieved by adding two
-compiler options for dynamic checks for access-before-elaboration on subprogram
-calls and generic instantiations (`-gnatE'), and stack overflow checking
-(`-fstack-check').
-
-Note that the result of a floating point arithmetic operation in overflow and
-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
-`-mieee' compiler flag must be used for achieving IEEE confirming
-behavior (although at the cost of a significant performance penalty), so
-infinite and NaN values are properly generated.
-
-@node Implementation of Ada 2012 Features,Security Hardening Features,Implementation of Specific Ada Features,Top
-@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{429}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{42a}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14}
-@chapter Implementation of Ada 2012 Features
-
-
-@geindex Ada 2012 implementation status
-
-@geindex -gnat12 option (gcc)
-
-@geindex pragma Ada_2012
-
-@geindex configuration pragma Ada_2012
-
-@geindex Ada_2012 configuration pragma
-
-This chapter contains a complete list of Ada 2012 features that have been
-implemented.
-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 @code{Ada_2012} is used.
-
-However, new pragmas, attributes, and restrictions are
-unconditionally available, since the Ada 95 standard allows the addition of
-new pragmas, attributes, and restrictions (there are exceptions, which are
-documented in the individual descriptions), and also certain packages
-were made available in earlier versions of Ada.
-
-An ISO date (YYYY-MM-DD) appears in parentheses on the description line.
-This date shows the implementation date of the feature. Any wavefront
-subsequent to this date will contain the indicated feature, as will any
-subsequent releases. A date of 0000-00-00 means that GNAT has always
-implemented the feature, or implemented it as soon as it appeared as a
-binding interpretation.
-
-Each feature corresponds to an Ada Issue (‘AI’) approved by the Ada
-standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012.
-The features are ordered based on the relevant sections of the Ada
-Reference Manual (“RM”).  When a given AI relates to multiple points
-in the RM, the earliest is used.
-
-A complete description of the AIs may be found in
-@indicateurl{http://www.ada-auth.org/ai05-summary.html}.
-
-@geindex AI-0176 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0176 Quantified expressions (2010-09-29)'
-
-Both universally and existentially quantified expressions are implemented.
-They use the new syntax for iterators proposed in AI05-139-2, as well as
-the standard Ada loop syntax.
-
-RM References:  1.01.04 (12)   2.09 (2/2)   4.04 (7)   4.05.09 (0)
-@end itemize
-
-@geindex AI-0079 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0079 Allow other_format characters in source (2010-07-10)'
-
-Wide characters in the unicode category `other_format' are now allowed in
-source programs between tokens, but not within a token such as an identifier.
-
-RM References:  2.01 (4/2)   2.02 (7)
-@end itemize
-
-@geindex AI-0091 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0091 Do not allow other_format in identifiers (0000-00-00)'
-
-Wide characters in the unicode category `other_format' are not permitted
-within  an identifier, since this can be a security problem. The error
-message for this case has been improved to be more specific, but GNAT has
-never allowed such characters to appear in identifiers.
-
-RM References:  2.03 (3.1/2)   2.03 (4/2)   2.03 (5/2)   2.03 (5.1/2)   2.03 (5.2/2)   2.03 (5.3/2)   2.09 (2/2)
-@end itemize
-
-@geindex AI-0100 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0100 Placement of pragmas  (2010-07-01)'
-
-This AI is an earlier version of AI-163. It simplifies the rules
-for legal placement of pragmas. In the case of lists that allow pragmas, if
-the list may have no elements, then the list may consist solely of pragmas.
-
-RM References:  2.08 (7)
-@end itemize
-
-@geindex AI-0163 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`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 @code{null} statement to make the sequence legal.
-
-RM References:  2.08 (7)   2.08 (16)
-@end itemize
-
-@geindex AI-0080 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0080 ‘View of’ not needed if clear from context (0000-00-00)'
-
-This is an editorial change only, described as non-testable in the AI.
-
-RM References:  3.01 (7)
-@end itemize
-
-@geindex AI-0183 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0183 Aspect specifications (2010-08-16)'
-
-Aspect specifications have been fully implemented except for pre and post-
-conditions, and type invariants, which have their own separate AI’s. All
-forms of declarations listed in the AI are supported. The following is a
-list of the aspects supported (with GNAT implementation aspects marked)
-@end itemize
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} 
-@headitem
-
-Supported Aspect
-
-@tab
-
-Source
-
-@item
-
-@code{Ada_2005}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Ada_2012}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Address}
-
-@tab
-
-@item
-
-@code{Alignment}
-
-@tab
-
-@item
-
-@code{Atomic}
-
-@tab
-
-@item
-
-@code{Atomic_Components}
-
-@tab
-
-@item
-
-@code{Bit_Order}
-
-@tab
-
-@item
-
-@code{Component_Size}
-
-@tab
-
-@item
-
-@code{Contract_Cases}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Discard_Names}
-
-@tab
-
-@item
-
-@code{External_Tag}
-
-@tab
-
-@item
-
-@code{Favor_Top_Level}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Inline}
-
-@tab
-
-@item
-
-@code{Inline_Always}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Invariant}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Machine_Radix}
-
-@tab
-
-@item
-
-@code{No_Return}
-
-@tab
-
-@item
-
-@code{Object_Size}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Pack}
-
-@tab
-
-@item
-
-@code{Persistent_BSS}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Post}
-
-@tab
-
-@item
-
-@code{Pre}
-
-@tab
-
-@item
-
-@code{Predicate}
-
-@tab
-
-@item
-
-@code{Preelaborable_Initialization}
-
-@tab
-
-@item
-
-@code{Pure_Function}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Remote_Access_Type}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Shared}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Size}
-
-@tab
-
-@item
-
-@code{Storage_Pool}
-
-@tab
-
-@item
-
-@code{Storage_Size}
-
-@tab
-
-@item
-
-@code{Stream_Size}
-
-@tab
-
-@item
-
-@code{Suppress}
-
-@tab
-
-@item
-
-@code{Suppress_Debug_Info}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Test_Case}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Thread_Local_Storage}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Type_Invariant}
-
-@tab
-
-@item
-
-@code{Unchecked_Union}
-
-@tab
-
-@item
-
-@code{Universal_Aliasing}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Unmodified}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Unreferenced}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Unreferenced_Objects}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Unsuppress}
-
-@tab
-
-@item
-
-@code{Value_Size}
-
-@tab
-
-– GNAT
-
-@item
-
-@code{Volatile}
-
-@tab
-
-@item
-
-@code{Volatile_Components}
-
-@tab
-
-@item
-
-@code{Warnings}
-
-@tab
-
-– GNAT
-
-@end multitable
-
-
-@quotation
-
-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).
-
-RM References:  3.02.01 (3)   3.02.02 (2)   3.03.01 (2/2)   3.08 (6)
-3.09.03 (1.1/2)   6.01 (2/2)   6.07 (2/2)   9.05.02 (2/2)   7.01 (3)   7.03
-(2)   7.03 (3)   9.01 (2/2)   9.01 (3/2)   9.04 (2/2)   9.04 (3/2)
-9.05.02 (2/2)   11.01 (2)   12.01 (3)   12.03 (2/2)   12.04 (2/2)   12.05 (2)
-12.06 (2.1/2)   12.06 (2.2/2)   12.07 (2)   13.01 (0.1/2)   13.03 (5/1)
-13.03.01 (0)
-@end quotation
-
-@geindex AI-0128 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0128 Inequality is a primitive operation (0000-00-00)'
-
-If an equality operator (“=”) is declared for a type, then the implicitly
-declared inequality operator (“/=”) is a primitive operation of the type.
-This is the only reasonable interpretation, and is the one always implemented
-by GNAT, but the RM was not entirely clear in making this point.
-
-RM References:  3.02.03 (6)   6.06 (6)
-@end itemize
-
-@geindex AI-0003 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`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 @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)
-5.04 (7)
-@end itemize
-
-@geindex AI-0120 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0120 Constant instance of protected object (0000-00-00)'
-
-This is an RM editorial change only. The section that lists objects that are
-constant failed to include the current instance of a protected object
-within a protected function. This has always been treated as a constant
-in GNAT.
-
-RM References:  3.03 (21)
-@end itemize
-
-@geindex AI-0008 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0008 General access to constrained objects (0000-00-00)'
-
-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. @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)
-@end itemize
-
-@geindex AI-0093 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0093 Additional rules use immutably limited (0000-00-00)'
-
-This is an editorial change only, to make more widespread use of the Ada 2012
-‘immutably limited’.
-
-RM References:  3.03 (23.4/3)
-@end itemize
-
-@geindex AI-0096 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0096 Deriving from formal private types (2010-07-20)'
-
-In general it is illegal for a type derived from a formal limited type to be
-nonlimited.  This AI makes an exception to this rule: derivation is legal
-if it appears in the private part of the generic, and the formal type is not
-tagged. If the type is tagged, the legality check must be applied to the
-private part of the package.
-
-RM References:  3.04 (5.1/2)   6.02 (7)
-@end itemize
-
-@geindex AI-0181 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`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 (@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.
-
-RM References:  3.05.02 (2/2)   A.01 (35/2)   A.03.03 (21)
-@end itemize
-
-@geindex AI-0182 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0182 Additional forms for' @code{Character'Value} `(0000-00-00)'
-
-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
-@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)
-@end itemize
-
-@geindex AI-0214 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0214 Defaulted discriminants for limited tagged (2010-10-01)'
-
-Ada 2012 relaxes the restriction that forbids discriminants of tagged types
-to have default expressions by allowing them when the type is limited. It
-is often useful to define a default value for a discriminant even though
-it can’t be changed by assignment.
-
-RM References:  3.07 (9.1/2)   3.07.02 (3)
-@end itemize
-
-@geindex AI-0102 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0102 Some implicit conversions are illegal (0000-00-00)'
-
-It is illegal to assign an anonymous access constant to an anonymous access
-variable. The RM did not have a clear rule to prevent this, but GNAT has
-always generated an error for this usage.
-
-RM References:  3.07 (16)   3.07.01 (9)   6.04.01 (6)   8.06 (27/2)
-@end itemize
-
-@geindex AI-0158 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0158 Generalizing membership tests (2010-09-16)'
-
-This AI extends the syntax of membership tests to simplify complex conditions
-that can be expressed as membership in a subset of values of any type. It
-introduces syntax for a list of expressions that may be used in loop contexts
-as well.
-
-RM References:  3.08.01 (5)   4.04 (3)   4.05.02 (3)   4.05.02 (5)   4.05.02 (27)
-@end itemize
-
-@geindex AI-0173 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0173 Testing if tags represent abstract types (2010-07-03)'
-
-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
-
-@geindex AI-0076 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0076 function with controlling result (0000-00-00)'
-
-This is an editorial change only. The RM defines calls with controlling
-results, but uses the term ‘function with controlling result’ without an
-explicit definition.
-
-RM References:  3.09.02 (2/2)
-@end itemize
-
-@geindex AI-0126 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0126 Dispatching with no declared operation (0000-00-00)'
-
-This AI clarifies dispatching rules, and simply confirms that dispatching
-executes the operation of the parent type when there is no explicitly or
-implicitly declared operation for the descendant type. This has always been
-the case in all versions of GNAT.
-
-RM References:  3.09.02 (20/2)   3.09.02 (20.1/2)   3.09.02 (20.2/2)
-@end itemize
-
-@geindex AI-0097 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0097 Treatment of abstract null extension (2010-07-19)'
-
-The RM as written implied that in some cases it was possible to create an
-object of an abstract type, by having an abstract extension inherit a non-
-abstract constructor from its parent type. This mistake has been corrected
-in GNAT and in the RM, and this construct is now illegal.
-
-RM References:  3.09.03 (4/2)
-@end itemize
-
-@geindex AI-0203 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0203 Extended return cannot be abstract (0000-00-00)'
-
-A return_subtype_indication cannot denote an abstract subtype. GNAT has never
-permitted such usage.
-
-RM References:  3.09.03 (8/3)
-@end itemize
-
-@geindex AI-0198 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0198 Inheriting abstract operators  (0000-00-00)'
-
-This AI resolves a conflict between two rules involving inherited abstract
-operations and predefined operators. If a derived numeric type inherits
-an abstract operator, it overrides the predefined one. This interpretation
-was always the one implemented in GNAT.
-
-RM References:  3.09.03 (4/3)
-@end itemize
-
-@geindex AI-0073 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0073 Functions returning abstract types (2010-07-10)'
-
-This AI covers a number of issues regarding returning abstract types. In
-particular generic functions cannot have abstract result types or access
-result types designated an abstract type. There are some other cases which
-are detailed in the AI. Note that this binding interpretation has not been
-retrofitted to operate before Ada 2012 mode, since it caused a significant
-number of regressions.
-
-RM References:  3.09.03 (8)   3.09.03 (10)   6.05 (8/2)
-@end itemize
-
-@geindex AI-0070 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0070 Elaboration of interface types (0000-00-00)'
-
-This is an editorial change only, there are no testable consequences short of
-checking for the absence of generated code for an interface declaration.
-
-RM References:  3.09.04 (18/2)
-@end itemize
-
-@geindex AI-0208 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0208 Characteristics of incomplete views (0000-00-00)'
-
-The wording in the Ada 2005 RM concerning characteristics of incomplete views
-was incorrect and implied that some programs intended to be legal were now
-illegal. GNAT had never considered such programs illegal, so it has always
-implemented the intent of this AI.
-
-RM References:  3.10.01 (2.4/2)   3.10.01 (2.6/2)
-@end itemize
-
-@geindex AI-0162 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0162 Incomplete type completed by partial view (2010-09-15)'
-
-Incomplete types are made more useful by allowing them to be completed by
-private types and private extensions.
-
-RM References:  3.10.01 (2.5/2)   3.10.01 (2.6/2)   3.10.01 (3)   3.10.01 (4/2)
-@end itemize
-
-@geindex AI-0098 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0098 Anonymous subprogram access restrictions (0000-00-00)'
-
-An unintentional omission in the RM implied some inconsistent restrictions on
-the use of anonymous access to subprogram values. These restrictions were not
-intentional, and have never been enforced by GNAT.
-
-RM References:  3.10.01 (6)   3.10.01 (9.2/2)
-@end itemize
-
-@geindex AI-0199 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0199 Aggregate with anonymous access components (2010-07-14)'
-
-A choice list in a record aggregate can include several components of
-(distinct) anonymous access types as long as they have matching designated
-subtypes.
-
-RM References:  4.03.01 (16)
-@end itemize
-
-@geindex AI-0220 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0220 Needed components for aggregates (0000-00-00)'
-
-This AI addresses a wording problem in the RM that appears to permit some
-complex cases of aggregates with nonstatic discriminants. GNAT has always
-implemented the intended semantics.
-
-RM References:  4.03.01 (17)
-@end itemize
-
-@geindex AI-0147 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0147 Conditional expressions (2009-03-29)'
-
-Conditional expressions are permitted. The form of such an expression is:
-
-@example
-(if expr then expr @{elsif expr then expr@} [else expr])
-@end example
-
-The parentheses can be omitted in contexts where parentheses are present
-anyway, such as subprogram arguments and pragma arguments. If the `else'
-clause is omitted, `else' `True' is assumed;
-thus @code{(if A then B)} is a way to conveniently represent
-`(A implies B)' in standard logic.
-
-RM References:  4.03.03 (15)   4.04 (1)   4.04 (7)   4.05.07 (0)   4.07 (2)
-4.07 (3)   4.09 (12)   4.09 (33)   5.03 (3)   5.03 (4)   7.05 (2.1/2)
-@end itemize
-
-@geindex AI-0037 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0037 Out-of-range box associations in aggregate (0000-00-00)'
-
-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.
-
-RM References:  4.03.03 (29)
-@end itemize
-
-@geindex AI-0123 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0123 Composability of equality (2010-04-13)'
-
-Equality of untagged record composes, so that the predefined equality for a
-composite type that includes a component of some untagged record type
-@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.
-
-This change is an incompatibility with previous versions of Ada, but it
-corrects a non-uniformity that was often a source of confusion. Analysis of
-a large number of industrial programs indicates that in those rare cases
-where a composite type had an untagged record component with a user-defined
-equality, either there was no use of the composite equality, or else the code
-expected the same composability as for tagged types, and thus had a bug that
-would be fixed by this change.
-
-RM References:  4.05.02 (9.7/2)   4.05.02 (14)   4.05.02 (15)   4.05.02 (24)
-8.05.04 (8)
-@end itemize
-
-@geindex AI-0088 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0088 The value of exponentiation (0000-00-00)'
-
-This AI clarifies the equivalence rule given for the dynamic semantics of
-exponentiation: the value of the operation can be obtained by repeated
-multiplication, but the operation can be implemented otherwise (for example
-using the familiar divide-by-two-and-square algorithm, even if this is less
-accurate), and does not imply repeated reads of a volatile base.
-
-RM References:  4.05.06 (11)
-@end itemize
-
-@geindex AI-0188 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0188 Case expressions (2010-01-09)'
-
-Case expressions are permitted. This allows use of constructs such as:
-
-@example
-X := (case Y is when 1 => 2, when 2 => 3, when others => 31)
-@end example
-
-RM References:  4.05.07 (0)   4.05.08 (0)   4.09 (12)   4.09 (33)
-@end itemize
-
-@geindex AI-0104 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0104 Null exclusion and uninitialized allocator (2010-07-15)'
-
-The assignment @code{Ptr := new not null Some_Ptr;} will raise
-@code{Constraint_Error} because the default value of the allocated object is
-`null'. This useless construct is illegal in Ada 2012.
-
-RM References:  4.08 (2)
-@end itemize
-
-@geindex AI-0157 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0157 Allocation/Deallocation from empty pool (2010-07-11)'
-
-Allocation and Deallocation from an empty storage pool (i.e. allocation or
-deallocation of a pointer for which a static storage size clause of zero
-has been given) is now illegal and is detected as such. GNAT
-previously gave a warning but not an error.
-
-RM References:  4.08 (5.3/2)   13.11.02 (4)   13.11.02 (17)
-@end itemize
-
-@geindex AI-0179 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0179 Statement not required after label (2010-04-10)'
-
-It is not necessary to have a statement following a label, so a label
-can appear at the end of a statement sequence without the need for putting a
-null statement afterwards, but it is not allowable to have only labels and
-no real statements in a statement sequence.
-
-RM References:  5.01 (2)
-@end itemize
-
-@geindex AI-0139-2 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0139-2 Syntactic sugar for iterators (2010-09-29)'
-
-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:  @code{for Elem of C}.
-
-RM References:  5.05
-@end itemize
-
-@geindex AI-0134 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0134 Profiles must match for full conformance (0000-00-00)'
-
-For full conformance, the profiles of anonymous-access-to-subprogram
-parameters must match. GNAT has always enforced this rule.
-
-RM References:  6.03.01 (18)
-@end itemize
-
-@geindex AI-0207 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0207 Mode conformance and access constant (0000-00-00)'
-
-This AI confirms that access_to_constant indication must match for mode
-conformance. This was implemented in GNAT when the qualifier was originally
-introduced in Ada 2005.
-
-RM References:  6.03.01 (16/2)
-@end itemize
-
-@geindex AI-0046 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0046 Null exclusion match for full conformance (2010-07-17)'
-
-For full conformance, in the case of access parameters, the null exclusion
-must match (either both or neither must have @code{not null}).
-
-RM References:  6.03.02 (18)
-@end itemize
-
-@geindex AI-0118 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0118 The association of parameter associations (0000-00-00)'
-
-This AI clarifies the rules for named associations in subprogram calls and
-generic instantiations. The rules have been in place since Ada 83.
-
-RM References:  6.04.01 (2)   12.03 (9)
-@end itemize
-
-@geindex AI-0196 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0196 Null exclusion tests for out parameters (0000-00-00)'
-
-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)
-@end itemize
-
-@geindex AI-0015 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0015 Constant return objects (0000-00-00)'
-
-The return object declared in an `extended_return_statement' may be
-declared constant. This was always intended, and GNAT has always allowed it.
-
-RM References:  6.05 (2.1/2)   3.03 (10/2)   3.03 (21)   6.05 (5/2)
-6.05 (5.7/2)
-@end itemize
-
-@geindex AI-0032 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0032 Extended return for class-wide functions (0000-00-00)'
-
-If a function returns a class-wide type, the object of an extended return
-statement can be declared with a specific type that is covered by the class-
-wide type. This has been implemented in GNAT since the introduction of
-extended returns. Note AI-0103 complements this AI by imposing matching
-rules for constrained return types.
-
-RM References:  6.05 (5.2/2)   6.05 (5.3/2)   6.05 (5.6/2)   6.05 (5.8/2)
-6.05 (8/2)
-@end itemize
-
-@geindex AI-0103 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0103 Static matching for extended return (2010-07-23)'
-
-If the return subtype of a function is an elementary type or a constrained
-type, the subtype indication in an extended return statement must match
-statically this return subtype.
-
-RM References:  6.05 (5.2/2)
-@end itemize
-
-@geindex AI-0058 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0058 Abnormal completion of an extended return (0000-00-00)'
-
-The RM had some incorrect wording implying wrong treatment of abnormal
-completion in an extended return. GNAT has always implemented the intended
-correct semantics as described by this AI.
-
-RM References:  6.05 (22/2)
-@end itemize
-
-@geindex AI-0050 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0050 Raising Constraint_Error early for function call (0000-00-00)'
-
-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.
-
-RM References:  6.05 (24/2)
-@end itemize
-
-@geindex AI-0125 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0125 Nonoverridable operations of an ancestor (2010-09-28)'
-
-In Ada 2012, the declaration of a primitive operation of a type extension
-or private extension can also override an inherited primitive that is not
-visible at the point of this declaration.
-
-RM References:  7.03.01 (6)   8.03 (23)   8.03.01 (5/2)   8.03.01 (6/2)
-@end itemize
-
-@geindex AI-0062 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0062 Null exclusions and deferred constants (0000-00-00)'
-
-A full constant may have a null exclusion even if its associated deferred
-constant does not. GNAT has always allowed this.
-
-RM References:  7.04 (6/2)   7.04 (7.1/2)
-@end itemize
-
-@geindex AI-0178 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0178 Incomplete views are limited (0000-00-00)'
-
-This AI clarifies the role of incomplete views and plugs an omission in the
-RM. GNAT always correctly restricted the use of incomplete views and types.
-
-RM References:  7.05 (3/2)   7.05 (6/2)
-@end itemize
-
-@geindex AI-0087 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0087 Actual for formal nonlimited derived type (2010-07-15)'
-
-The actual for a formal nonlimited derived type cannot be limited. In
-particular, a formal derived type that extends a limited interface but which
-is not explicitly limited cannot be instantiated with a limited type.
-
-RM References:  7.05 (5/2)   12.05.01 (5.1/2)
-@end itemize
-
-@geindex AI-0099 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0099 Tag determines whether finalization needed (0000-00-00)'
-
-This AI clarifies that ‘needs finalization’ is part of dynamic semantics,
-and therefore depends on the run-time characteristics of an object (i.e. its
-tag) and not on its nominal type. As the AI indicates: “we do not expect
-this to affect any implementation’’.
-
-RM References:  7.06.01 (6)   7.06.01 (7)   7.06.01 (8)   7.06.01 (9/2)
-@end itemize
-
-@geindex AI-0064 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0064 Redundant finalization rule (0000-00-00)'
-
-This is an editorial change only. The intended behavior is already checked
-by an existing ACATS test, which GNAT has always executed correctly.
-
-RM References:  7.06.01 (17.1/1)
-@end itemize
-
-@geindex AI-0026 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0026 Missing rules for Unchecked_Union (2010-07-07)'
-
-Record representation clauses concerning Unchecked_Union types cannot mention
-the discriminant of the type. The type of a component declared in the variant
-part of an Unchecked_Union cannot be controlled, have controlled components,
-nor have protected or task parts. If an Unchecked_Union type is declared
-within the body of a generic unit or its descendants, then the type of a
-component declared in the variant part cannot be a formal private type or a
-formal private extension declared within the same generic unit.
-
-RM References:  7.06 (9.4/2)   B.03.03 (9/2)   B.03.03 (10/2)
-@end itemize
-
-@geindex AI-0205 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0205 Extended return declares visible name (0000-00-00)'
-
-This AI corrects a simple omission in the RM. Return objects have always
-been visible within an extended return statement.
-
-RM References:  8.03 (17)
-@end itemize
-
-@geindex AI-0042 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0042 Overriding versus implemented-by (0000-00-00)'
-
-This AI fixes a wording gap in the RM. An operation of a synchronized
-interface can be implemented by a protected or task entry, but the abstract
-operation is not being overridden in the usual sense, and it must be stated
-separately that this implementation is legal. This has always been the case
-in GNAT.
-
-RM References:  9.01 (9.2/2)   9.04 (11.1/2)
-@end itemize
-
-@geindex AI-0030 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0030 Requeue on synchronized interfaces (2010-07-19)'
-
-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
-@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.
-
-RM References:  9.05 (9)   9.05.04 (2)   9.05.04 (3)   9.05.04 (5)
-9.05.04 (6)   9.05.04 (7)   9.05.04 (12)
-@end itemize
-
-@geindex AI-0201 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0201 Independence of atomic object components (2010-07-22)'
-
-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
-other appropriately addressable component sizes (e.g. 16 for 8-bit
-characters) also preserves independence. GNAT now gives very clear warnings
-both for the declaration of such a type, and for any assignment to its components.
-
-RM References:  9.10 (1/3)   C.06 (22/2)   C.06 (23/2)
-@end itemize
-
-@geindex AI-0009 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0009 Pragma Independent[_Components] (2010-07-23)'
-
-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.
-
-RM References:  9.10 (1)   13.01 (15/1)   13.02 (9)   13.03 (13)   C.06 (2)
-C.06 (4)   C.06 (6)   C.06 (9)   C.06 (13)   C.06 (14)
-@end itemize
-
-@geindex AI-0072 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0072 Task signalling using ‘Terminated (0000-00-00)'
-
-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.
-
-RM References:  9.10 (6.1/1)
-@end itemize
-
-@geindex AI-0108 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0108 Limited incomplete view and discriminants (0000-00-00)'
-
-This AI confirms that an incomplete type from a limited view does not have
-discriminants. This has always been the case in GNAT.
-
-RM References:  10.01.01 (12.3/2)
-@end itemize
-
-@geindex AI-0129 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0129 Limited views and incomplete types (0000-00-00)'
-
-This AI clarifies the description of limited views: a limited view of a
-package includes only one view of a type that has an incomplete declaration
-and a full declaration (there is no possible ambiguity in a client package).
-This AI also fixes an omission: a nested package in the private part has no
-limited view. GNAT always implemented this correctly.
-
-RM References:  10.01.01 (12.2/2)   10.01.01 (12.3/2)
-@end itemize
-
-@geindex AI-0077 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0077 Limited withs and scope of declarations (0000-00-00)'
-
-This AI clarifies that a declaration does not include a context clause,
-and confirms that it is illegal to have a context in which both a limited
-and a nonlimited view of a package are accessible. Such double visibility
-was always rejected by GNAT.
-
-RM References:  10.01.02 (12/2)   10.01.02 (21/2)   10.01.02 (22/2)
-@end itemize
-
-@geindex AI-0122 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0122 Private with and children of generics (0000-00-00)'
-
-This AI clarifies the visibility of private children of generic units within
-instantiations of a parent. GNAT has always handled this correctly.
-
-RM References:  10.01.02 (12/2)
-@end itemize
-
-@geindex AI-0040 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0040 Limited with clauses on descendant (0000-00-00)'
-
-This AI confirms that a limited with clause in a child unit cannot name
-an ancestor of the unit. This has always been checked in GNAT.
-
-RM References:  10.01.02 (20/2)
-@end itemize
-
-@geindex AI-0132 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0132 Placement of library unit pragmas (0000-00-00)'
-
-This AI fills a gap in the description of library unit pragmas. The pragma
-clearly must apply to a library unit, even if it does not carry the name
-of the enclosing unit. GNAT has always enforced the required check.
-
-RM References:  10.01.05 (7)
-@end itemize
-
-@geindex AI-0034 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0034 Categorization of limited views (0000-00-00)'
-
-The RM makes certain limited with clauses illegal because of categorization
-considerations, when the corresponding normal with would be legal. This is
-not intended, and GNAT has always implemented the recommended behavior.
-
-RM References:  10.02.01 (11/1)   10.02.01 (17/2)
-@end itemize
-
-@geindex AI-0035 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0035 Inconsistencies with Pure units (0000-00-00)'
-
-This AI remedies some inconsistencies in the legality rules for Pure units.
-Derived access types are legal in a pure unit (on the assumption that the
-rule for a zero storage pool size has been enforced on the ancestor type).
-The rules are enforced in generic instances and in subunits. GNAT has always
-implemented the recommended behavior.
-
-RM References:  10.02.01 (15.1/2)   10.02.01 (15.4/2)   10.02.01 (15.5/2)   10.02.01 (17/2)
-@end itemize
-
-@geindex AI-0219 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0219 Pure permissions and limited parameters (2010-05-25)'
-
-This AI refines the rules for the cases with limited parameters which do not
-allow the implementations to omit ‘redundant’. GNAT now properly conforms
-to the requirements of this binding interpretation.
-
-RM References:  10.02.01 (18/2)
-@end itemize
-
-@geindex AI-0043 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0043 Rules about raising exceptions (0000-00-00)'
-
-This AI covers various omissions in the RM regarding the raising of
-exceptions. GNAT has always implemented the intended semantics.
-
-RM References:  11.04.01 (10.1/2)   11 (2)
-@end itemize
-
-@geindex AI-0200 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0200 Mismatches in formal package declarations (0000-00-00)'
-
-This AI plugs a gap in the RM which appeared to allow some obviously intended
-illegal instantiations. GNAT has never allowed these instantiations.
-
-RM References:  12.07 (16)
-@end itemize
-
-@geindex AI-0112 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0112 Detection of duplicate pragmas (2010-07-24)'
-
-This AI concerns giving names to various representation aspects, but the
-practical effect is simply to make the use of duplicate
-@code{Atomic[_Components]},
-@code{Volatile[_Components]}, and
-@code{Independent[_Components]} pragmas illegal, and GNAT
-now performs this required check.
-
-RM References:  13.01 (8)
-@end itemize
-
-@geindex AI-0106 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0106 No representation pragmas on generic formals (0000-00-00)'
-
-The RM appeared to allow representation pragmas on generic formal parameters,
-but this was not intended, and GNAT has never permitted this usage.
-
-RM References:  13.01 (9.1/1)
-@end itemize
-
-@geindex AI-0012 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)'
-
-It is now illegal to give an inappropriate component size or a pragma
-@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.
-
-RM References:  13.02 (6.1/2)   13.02 (7)   C.06 (10)   C.06 (11)   C.06 (21)
-@end itemize
-
-@geindex AI-0039 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0039 Stream attributes cannot be dynamic (0000-00-00)'
-
-The RM permitted the use of dynamic expressions (such as @code{ptr.all})`
-for stream attributes, but these were never useful and are now illegal. GNAT
-has always regarded such expressions as illegal.
-
-RM References:  13.03 (4)   13.03 (6)   13.13.02 (38/2)
-@end itemize
-
-@geindex AI-0095 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0095 Address of intrinsic subprograms (0000-00-00)'
-
-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
-
-@geindex AI-0116 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0116 Alignment of class-wide objects (0000-00-00)'
-
-This AI requires that the alignment of a class-wide object be no greater
-than the alignment of any type in the class. GNAT has always followed this
-recommendation.
-
-RM References:  13.03 (29)   13.11 (16)
-@end itemize
-
-@geindex AI-0146 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0146 Type invariants (2009-09-21)'
-
-Type invariants may be specified for private types using the aspect notation.
-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
-declarations for the private type that are default initialized, and
-[`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 @code{Invariant} for @code{Type_Invariant} and
-@code{Invariant'Class} for @code{Type_Invariant'Class}.
-
-RM References:  13.03.03 (00)
-@end itemize
-
-@geindex AI-0078 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)'
-
-In Ada 2012, compilers are required to support unchecked conversion where the
-target alignment is a multiple of the source alignment. GNAT always supported
-this case (and indeed all cases of differing alignments, doing copies where
-required if the alignment was reduced).
-
-RM References:  13.09 (7)
-@end itemize
-
-@geindex AI-0195 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0195 Invalid value handling is implementation defined (2010-07-03)'
-
-The handling of invalid values is now designated to be implementation
-defined. This is a documentation change only, requiring Annex M in the GNAT
-Reference Manual to document this handling.
-In GNAT, checks for invalid values are made
-only when necessary to avoid erroneous behavior. Operations like assignments
-which cannot cause erroneous behavior ignore the possibility of invalid
-values and do not do a check. The date given above applies only to the
-documentation change, this behavior has always been implemented by GNAT.
-
-RM References:  13.09.01 (10)
-@end itemize
-
-@geindex AI-0193 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0193 Alignment of allocators (2010-09-16)'
-
-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)
-13.11.01 (2)   13.11.01 (3)
-@end itemize
-
-@geindex AI-0177 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0177 Parameterized expressions (2010-07-10)'
-
-The new Ada 2012 notion of parameterized expressions is implemented. The form
-is:
-
-@example
-function-specification is (expression)
-@end example
-
-This is exactly equivalent to the
-corresponding function body that returns the expression, but it can appear
-in a package spec. Note that the expression must be parenthesized.
-
-RM References:  13.11.01 (3/2)
-@end itemize
-
-@geindex AI-0033 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)'
-
-Neither of these two pragmas may appear within a generic template, because
-the generic might be instantiated at other than the library level.
-
-RM References:  13.11.02 (16)   C.03.01 (7/2)   C.03.01 (8/2)
-@end itemize
-
-@geindex AI-0161 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)'
-
-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.
-
-RM References:  13.12.01 (4/2)   13.13.02 (40/2)   13.13.02 (52/2)
-@end itemize
-
-@geindex AI-0194 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0194 Value of Stream_Size attribute (0000-00-00)'
-
-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
-this interpretation.
-
-RM References:  13.13.02 (1.2/2)
-@end itemize
-
-@geindex AI-0109 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0109 Redundant check in S’Class’Input (0000-00-00)'
-
-This AI is an editorial change only. It removes the need for a tag check
-that can never fail.
-
-RM References:  13.13.02 (34/2)
-@end itemize
-
-@geindex AI-0007 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0007 Stream read and private scalar types (0000-00-00)'
-
-The RM as written appeared to limit the possibilities of declaring read
-attribute procedures for private scalar types. This limitation was not
-intended, and has never been enforced by GNAT.
-
-RM References:  13.13.02 (50/2)   13.13.02 (51/2)
-@end itemize
-
-@geindex AI-0065 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0065 Remote access types and external streaming (0000-00-00)'
-
-This AI clarifies the fact that all remote access types support external
-streaming. This fixes an obvious oversight in the definition of the
-language, and GNAT always implemented the intended correct rules.
-
-RM References:  13.13.02 (52/2)
-@end itemize
-
-@geindex AI-0019 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0019 Freezing of primitives for tagged types (0000-00-00)'
-
-The RM suggests that primitive subprograms of a specific tagged type are
-frozen when the tagged type is frozen. This would be an incompatible change
-and is not intended. GNAT has never attempted this kind of freezing and its
-behavior is consistent with the recommendation of this AI.
-
-RM References:  13.14 (2)   13.14 (3/1)   13.14 (8.1/1)   13.14 (10)   13.14 (14)   13.14 (15.1/2)
-@end itemize
-
-@geindex AI-0017 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0017 Freezing and incomplete types (0000-00-00)'
-
-So-called ‘Taft-amendment types’ (i.e., types that are completed in package
-bodies) are not frozen by the occurrence of bodies in the
-enclosing declarative part. GNAT always implemented this properly.
-
-RM References:  13.14 (3/1)
-@end itemize
-
-@geindex AI-0060 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0060 Extended definition of remote access types (0000-00-00)'
-
-This AI extends the definition of remote access types to include access
-to limited, synchronized, protected or task class-wide interface types.
-GNAT already implemented this extension.
-
-RM References:  A (4)   E.02.02 (9/1)   E.02.02 (9.2/1)   E.02.02 (14/2)   E.02.02 (18)
-@end itemize
-
-@geindex AI-0114 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0114 Classification of letters (0000-00-00)'
-
-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 @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)
-@end itemize
-
-@geindex AI-0185 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)'
-
-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
-
-@geindex AI-0031 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0031 Add From parameter to Find_Token (2010-07-25)'
-
-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 @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.
-
-RM References:  A.04.03 (16)   A.04.03 (67)   A.04.03 (68/1)   A.04.04 (51)
-A.04.05 (46)
-@end itemize
-
-@geindex AI-0056 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0056 Index on null string returns zero (0000-00-00)'
-
-The wording in the Ada 2005 RM implied an incompatible handling of the
-@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.
-
-RM References:  A.04.03 (56.2/2)   A.04.03 (58.5/2)
-@end itemize
-
-@geindex AI-0137 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0137 String encoding package (2010-03-25)'
-
-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
-@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 @code{Wide_Wide_Strings}, these packages are available in
-Ada 95 and Ada 2005 mode as well as Ada 2012 mode.
-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 @code{Wide_Wide_Character}).
-
-RM References:  A.04.11
-@end itemize
-
-@geindex AI-0038 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0038 Minor errors in Text_IO (0000-00-00)'
-
-These are minor errors in the description on three points. The intent on
-all these points has always been clear, and GNAT has always implemented the
-correct intended semantics.
-
-RM References:  A.10.05 (37)   A.10.07 (8/1)   A.10.07 (10)   A.10.07 (12)   A.10.08 (10)   A.10.08 (24)
-@end itemize
-
-@geindex AI-0044 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0044 Restrictions on container instantiations (0000-00-00)'
-
-This AI places restrictions on allowed instantiations of generic containers.
-These restrictions are not checked by the compiler, so there is nothing to
-change in the implementation. This affects only the RM documentation.
-
-RM References:  A.18 (4/2)   A.18.02 (231/2)   A.18.03 (145/2)   A.18.06 (56/2)   A.18.08 (66/2)   A.18.09 (79/2)   A.18.26 (5/2)   A.18.26 (9/2)
-@end itemize
-
-@geindex AI-0127 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0127 Adding Locale Capabilities (2010-09-29)'
-
-This package provides an interface for identifying the current locale.
-
-RM References:  A.19    A.19.01    A.19.02    A.19.03    A.19.05    A.19.06
-A.19.07    A.19.08    A.19.09    A.19.10    A.19.11    A.19.12    A.19.13
-@end itemize
-
-@geindex AI-0002 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0002 Export C with unconstrained arrays (0000-00-00)'
-
-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 @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.
-
-RM References:  B.01 (17)   B.03 (62)   B.03 (71.1/2)
-@end itemize
-
-@geindex AI05-0216 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)'
-
-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.
-Thus this is a documentation change in the RM only.
-
-RM References:  D.07 (3/3)
-@end itemize
-
-@geindex AI-0211 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)'
-
-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
-
-@geindex AI-0190 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0190 pragma Default_Storage_Pool (2010-09-15)'
-
-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 (`new') to have an explicit storage pool,
-or you can declare a pool globally to be used for all access types that lack
-an explicit one.
-
-RM References:  D.07 (8)
-@end itemize
-
-@geindex AI-0189 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0189 No_Allocators_After_Elaboration (2010-01-23)'
-
-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
-GNAT does not attempt. But the static cases of allocators in a task body or
-in the body of the main program are detected and flagged at compile or bind
-time.
-
-RM References:  D.07 (19.1/2)   H.04 (23.3/2)
-@end itemize
-
-@geindex AI-0171 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)'
-
-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
-@end itemize
-
-@geindex AI-0210 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0210 Correct Timing_Events metric (0000-00-00)'
-
-This is a documentation only issue regarding wording of metric requirements,
-that does not affect the implementation of the compiler.
-
-RM References:  D.15 (24/2)
-@end itemize
-
-@geindex AI-0206 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0206 Remote types packages and preelaborate (2010-07-24)'
-
-Remote types packages are now allowed to depend on preelaborated packages.
-This was formerly considered illegal.
-
-RM References:  E.02.02 (6)
-@end itemize
-
-@geindex AI-0152 (Ada 2012 feature)
-
-
-@itemize *
-
-@item 
-`AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)'
-
-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 Security Hardening Features,Obsolescent Features,Implementation of Ada 2012 Features,Top
-@anchor{gnat_rm/security_hardening_features doc}@anchor{42b}@anchor{gnat_rm/security_hardening_features id1}@anchor{42c}@anchor{gnat_rm/security_hardening_features security-hardening-features}@anchor{15}
-@chapter Security Hardening Features
-
-
-This chapter describes Ada extensions aimed at security hardening that
-are provided by GNAT.
-
-The features in this chapter are currently experimental and subject to
-change.
-
-@c Register Scrubbing:
-
-@menu
-* Register Scrubbing:: 
-* Stack Scrubbing:: 
-* Hardened Conditionals:: 
-* Hardened Booleans:: 
-* Control Flow Redundancy:: 
-
-@end menu
-
-@node Register Scrubbing,Stack Scrubbing,,Security Hardening Features
-@anchor{gnat_rm/security_hardening_features register-scrubbing}@anchor{42d}
-@section Register Scrubbing
-
-
-GNAT can generate code to zero-out hardware registers before returning
-from a subprogram.
-
-It can be enabled with the @code{-fzero-call-used-regs=`choice'}
-command-line option, to affect all subprograms in a compilation, and
-with a @code{Machine_Attribute} pragma, to affect only specific
-subprograms.
-
-@example
-procedure Foo;
-pragma Machine_Attribute (Foo, "zero_call_used_regs", "used");
---  Before returning, Foo scrubs only call-clobbered registers
---  that it uses itself.
-
-function Bar return Integer;
-pragma Machine_Attribute (Bar, "zero_call_used_regs", "all");
---  Before returning, Bar scrubs all call-clobbered registers.
-@end example
-
-For usage and more details on the command-line option, on the
-@code{zero_call_used_regs} attribute, and on their use with other
-programming languages, see @cite{Using the GNU Compiler Collection (GCC)}.
-
-@c Stack Scrubbing:
-
-@node Stack Scrubbing,Hardened Conditionals,Register Scrubbing,Security Hardening Features
-@anchor{gnat_rm/security_hardening_features stack-scrubbing}@anchor{42e}
-@section Stack Scrubbing
-
-
-GNAT can generate code to zero-out stack frames used by subprograms.
-
-It can be activated with the @code{Machine_Attribute} pragma, on
-specific subprograms and variables, or their types.  (This attribute
-always applies to a type, even when it is associated with a subprogram
-or a variable.)
-
-@example
-function Foo returns Integer;
-pragma Machine_Attribute (Foo, "strub");
---  Foo and its callers are modified so as to scrub the stack
---  space used by Foo after it returns.  Shorthand for:
---  pragma Machine_Attribute (Foo, "strub", "at-calls");
-
-procedure Bar;
-pragma Machine_Attribute (Bar, "strub", "internal");
---  Bar is turned into a wrapper for its original body,
---  and they scrub the stack used by the original body.
-
-Var : Integer;
-pragma Machine_Attribute (Var, "strub");
---  Reading from Var in a subprogram enables stack scrubbing
---  of the stack space used by the subprogram.  Furthermore, if
---  Var is declared within a subprogram, this also enables
---  scrubbing of the stack space used by that subprogram.
-@end example
-
-Given these declarations, Foo has its type and body modified as
-follows:
-
-@example
-function Foo (<WaterMark> : in out System.Address) returns Integer
-is
-  --  ...
-begin
-  <__strub_update> (<WaterMark>);  --  Updates the stack WaterMark.
-  --  ...
-end;
-@end example
-
-whereas its callers are modified from:
-
-@example
-X := Foo;
-@end example
-
-to:
-
-@example
-declare
-  <WaterMark> : System.Address;
-begin
-  <__strub_enter> (<WaterMark>);  -- Initialize <WaterMark>.
-  X := Foo (<WaterMark>);
-  <__strub_leave> (<WaterMark>);  -- Scrubs stack up to <WaterMark>.
-end;
-@end example
-
-As for Bar, because it is strubbed in internal mode, its callers are
-not modified.  Its definition is modified roughly as follows:
-
-@example
-procedure Bar is
-  <WaterMark> : System.Address;
-  procedure Strubbed_Bar (<WaterMark> : in out System.Address) is
-  begin
-    <__strub_update> (<WaterMark>);  --  Updates the stack WaterMark.
-    -- original Bar body.
-  end Strubbed_Bar;
-begin
-  <__strub_enter> (<WaterMark>);  -- Initialize <WaterMark>.
-  Strubbed_Bar (<WaterMark>);
-  <__strub_leave> (<WaterMark>);  -- Scrubs stack up to <WaterMark>.
-end Bar;
-@end example
-
-There are also @code{-fstrub=`choice'} command-line options to
-control default settings.  For usage and more details on the
-command-line options, on the @code{strub} attribute, and their use with
-other programming languages, see @cite{Using the GNU Compiler Collection (GCC)}.
-
-Note that Ada secondary stacks are not scrubbed.  The restriction
-@code{No_Secondary_Stack} avoids their use, and thus their accidental
-preservation of data that should be scrubbed.
-
-Attributes @code{Access} and @code{Unconstrained_Access} of variables and
-constants with @code{strub} enabled require types with @code{strub} enabled;
-there is no way to express an access-to-strub type otherwise.
-@code{Unchecked_Access} bypasses this constraint, but the resulting
-access type designates a non-strub type.
-
-@example
-VI : aliased Integer;
-pragma Machine_Attribute (VI, "strub");
-XsVI : access Integer := VI'Access; -- Error.
-UXsVI : access Integer := VI'Unchecked_Access; -- OK,
---  UXsVI does *not* enable strub in subprograms that
---  dereference it to obtain the UXsVI.all value.
-
-type Strub_Int is new Integer;
-pragma Machine_Attribute (Strub_Int, "strub");
-VSI : aliased Strub_Int;
-XsVSI : access Strub_Int := VSI'Access; -- OK,
---  VSI and XsVSI.all both enable strub in subprograms that
---  read their values.
-@end example
-
-Every access-to-subprogram type, renaming, and overriding and
-overridden dispatching operations that may refer to a subprogram with
-an attribute-modified interface must be annotated with the same
-interface-modifying attribute.  Access-to-subprogram types can be
-explicitly converted to different strub modes, as long as they are
-interface-compatible (i.e., adding or removing @code{at-calls} is not
-allowed).  For example, a @code{strub}-@code{disabled} subprogram can be
-turned @code{callable} through such an explicit conversion:
-
-@example
-type TBar is access procedure;
-
-type TBar_Callable is access procedure;
-pragma Machine_Attribute (TBar_Callable, "strub", "callable");
---  The attribute modifies the procedure type, rather than the
---  access type, because of the extra argument after "strub",
---  only applicable to subprogram types.
-
-Bar_Callable_Ptr : constant TBar_Callable
-           := TBar_Callable (TBar'(Bar'Access));
-
-procedure Bar_Callable renames Bar_Callable_Ptr.all;
-pragma Machine_Attribute (Bar_Callable, "strub", "callable");
-@end example
-
-Note that the renaming declaration is expanded to a full subprogram
-body, it won’t be just an alias.  Only if it is inlined will it be as
-efficient as a call by dereferencing the access-to-subprogram constant
-Bar_Callable_Ptr.
-
-@c Hardened Conditionals:
-
-@node Hardened Conditionals,Hardened Booleans,Stack Scrubbing,Security Hardening Features
-@anchor{gnat_rm/security_hardening_features hardened-conditionals}@anchor{42f}
-@section Hardened Conditionals
-
-
-GNAT can harden conditionals to protect against control-flow attacks.
-
-This is accomplished by two complementary transformations, each
-activated by a separate command-line option.
-
-The option @code{-fharden-compares} enables hardening of compares
-that compute results stored in variables, adding verification that the
-reversed compare yields the opposite result, turning:
-
-@example
-B := X = Y;
-@end example
-
-into:
-
-@example
-B := X = Y;
-declare
-  NotB : Boolean := X /= Y; -- Computed independently of B.
-begin
-  if B = NotB then
-    <__builtin_trap>;
-  end if;
-end;
-@end example
-
-The option @code{-fharden-conditional-branches} enables hardening
-of compares that guard conditional branches, adding verification of
-the reversed compare to both execution paths, turning:
-
-@example
-if X = Y then
-  X := Z + 1;
-else
-  Y := Z - 1;
-end if;
-@end example
-
-into:
-
-@example
-if X = Y then
-  if X /= Y then -- Computed independently of X = Y.
-    <__builtin_trap>;
-  end if;
-  X := Z + 1;
-else
-  if X /= Y then -- Computed independently of X = Y.
-    null;
-  else
-    <__builtin_trap>;
-  end if;
-  Y := Z - 1;
-end if;
-@end example
-
-These transformations are introduced late in the compilation pipeline,
-long after boolean expressions are decomposed into separate compares,
-each one turned into either a conditional branch or a compare whose
-result is stored in a boolean variable or temporary.  Compiler
-optimizations, if enabled, may also turn conditional branches into
-stored compares, and vice-versa, or into operations with implied
-conditionals (e.g. MIN and MAX).  Conditionals may also be optimized
-out entirely, if their value can be determined at compile time, and
-occasionally multiple compares can be combined into one.
-
-It is thus difficult to predict which of these two options will affect
-a specific compare operation expressed in source code.  Using both
-options ensures that every compare that is neither optimized out nor
-optimized into implied conditionals will be hardened.
-
-The addition of reversed compares can be observed by enabling the dump
-files of the corresponding passes, through command-line options
-@code{-fdump-tree-hardcmp} and @code{-fdump-tree-hardcbr},
-respectively.
-
-They are separate options, however, because of the significantly
-different performance impact of the hardening transformations.
-
-For usage and more details on the command-line options, see
-@cite{Using the GNU Compiler Collection (GCC)}.  These options can
-be used with other programming languages supported by GCC.
-
-@c Hardened Booleans:
-
-@node Hardened Booleans,Control Flow Redundancy,Hardened Conditionals,Security Hardening Features
-@anchor{gnat_rm/security_hardening_features hardened-booleans}@anchor{430}
-@section Hardened Booleans
-
-
-Ada has built-in support for introducing boolean types with
-alternative representations, using representation clauses:
-
-@example
-type HBool is new Boolean;
-for HBool use (16#5a#, 16#a5#);
-for HBool'Size use 8;
-@end example
-
-When validity checking is enabled, the compiler will check that
-variables of such types hold values corresponding to the selected
-representations.
-
-There are multiple strategies for where to introduce validity checking
-(see @code{-gnatV} options).  Their goal is to guard against
-various kinds of programming errors, and GNAT strives to omit checks
-when program logic rules out an invalid value, and optimizers may
-further remove checks found to be redundant.
-
-For additional hardening, the @code{hardbool} @code{Machine_Attribute}
-pragma can be used to annotate boolean types with representation
-clauses, so that expressions of such types used as conditions are
-checked even when compiling with @code{-gnatVT}:
-
-@example
-pragma Machine_Attribute (HBool, "hardbool");
-
-function To_Boolean (X : HBool) returns Boolean is (Boolean (X));
-@end example
-
-is compiled roughly like:
-
-@example
-function To_Boolean (X : HBool) returns Boolean is
-begin
-  if X not in True | False then
-    raise Constraint_Error;
-  elsif X in True then
-    return True;
-  else
-    return False;
-  end if;
-end To_Boolean;
-@end example
-
-Note that @code{-gnatVn} will disable even @code{hardbool} testing.
-
-Analogous behavior is available as a GCC extension to the C and
-Objective C programming languages, through the @code{hardbool} attribute,
-with the difference that, instead of raising a Constraint_Error
-exception, when a hardened boolean variable is found to hold a value
-that stands for neither True nor False, the program traps.  For usage
-and more details on that attribute, see @cite{Using the GNU Compiler Collection (GCC)}.
-
-@c Control Flow Redundancy:
-
-@node Control Flow Redundancy,,Hardened Booleans,Security Hardening Features
-@anchor{gnat_rm/security_hardening_features control-flow-redundancy}@anchor{431}
-@section Control Flow Redundancy
-
-
-GNAT can guard against unexpected execution flows, such as branching
-into the middle of subprograms, as in Return Oriented Programming
-exploits.
-
-In units compiled with @code{-fharden-control-flow-redundancy},
-subprograms are instrumented so that, every time they are called,
-basic blocks take note as control flows through them, and, before
-returning, subprograms verify that the taken notes are consistent with
-the control-flow graph.
-
-Functions with too many basic blocks, or with multiple return points,
-call a run-time function to perform the verification.  Other functions
-perform the verification inline before returning.
-
-Optimizing the inlined verification can be quite time consuming, so
-the default upper limit for the inline mode is set at 16 blocks.
-Command-line option @code{--param hardcfr-max-inline-blocks=} can
-override it.
-
-Even though typically sparse control-flow graphs exhibit run-time
-verification time nearly proportional to the block count of a
-subprogram, it may become very significant for generated subprograms
-with thousands of blocks.  Command-line option
-@code{--param hardcfr-max-blocks=} can set an upper limit for
-instrumentation.
-
-For each block that is marked as visited, the mechanism checks that at
-least one of its predecessors, and at least one of its successors, are
-also marked as visited.
-
-Verification is performed just before returning.  Subprogram
-executions that complete by raising or propagating an exception bypass
-verification-and-return points.  A subprogram that can only complete
-by raising or propagating an exception may have instrumentation
-disabled altogether.
-
-The instrumentation for hardening with control flow redundancy can be
-observed in dump files generated by the command-line option
-@code{-fdump-tree-hardcfr}.
-
-For more details on the control flow redundancy command-line options,
-see @cite{Using the GNU Compiler Collection (GCC)}.  These options
-can be used with other programming languages supported by GCC.
-
-@node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top
-@anchor{gnat_rm/obsolescent_features doc}@anchor{432}@anchor{gnat_rm/obsolescent_features id1}@anchor{433}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16}
-@chapter Obsolescent Features
-
-
-This chapter describes features that are provided by GNAT, but are
-considered obsolescent since there are preferred ways of achieving
-the same effect. These features are provided solely for historical
-compatibility purposes.
-
-@menu
-* pragma No_Run_Time:: 
-* pragma Ravenscar:: 
-* pragma Restricted_Run_Time:: 
-* pragma Task_Info:: 
-* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 
-
-@end menu
-
-@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features
-@anchor{gnat_rm/obsolescent_features id2}@anchor{434}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{435}
-@section pragma No_Run_Time
-
-
-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
-the use of any language features requiring run-time support code. The
-preferred usage is to use an appropriately configured run-time that
-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{436}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{437}
-@section pragma Ravenscar
-
-
-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 id4}@anchor{438}@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{439}
-@section pragma Restricted_Run_Time
-
-
-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 id5}@anchor{43a}@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{43b}
-@section pragma Task_Info
-
-
-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 processors.
-
-Syntax
-
-@example
-pragma Task_Info (EXPRESSION);
-@end example
-
-This pragma appears within a task definition (like pragma
-@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
-in the spec of package System.Task_Info in the runtime
-library.
-
-@node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features
-@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{43c}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{43d}
-@section package System.Task_Info (@code{s-tasinf.ads})
-
-
-This package provides target dependent functionality that is used
-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 doc}@anchor{43e}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{17}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{43f}
-@chapter Compatibility and Porting Guide
-
-
-This chapter presents some guidelines for developing portable Ada code,
-describes the compatibility issues that may arise between
-GNAT and other Ada compilation systems (including those for Ada 83),
-and shows how GNAT can expedite porting
-applications developed in other Ada environments.
-
-@menu
-* Writing Portable Fixed-Point Declarations:: 
-* Compatibility with Ada 83:: 
-* Compatibility between Ada 95 and Ada 2005:: 
-* Implementation-dependent characteristics:: 
-* Compatibility with Other Ada Systems:: 
-* Representation Clauses:: 
-* Compatibility with HP Ada 83:: 
-
-@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{440}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{441}
-@section Writing Portable Fixed-Point Declarations
-
-
-The Ada Reference Manual gives an implementation freedom to choose bounds
-that are narrower by @code{Small} from the given bounds.
-For example, if we write
-
-@example
-type F1 is delta 1.0 range -128.0 .. +128.0;
-@end example
-
-then the implementation is allowed to choose -128.0 .. +127.0 if it
-likes, but is not required to do so.
-
-This leads to possible portability problems, so let’s have a closer
-look at this, and figure out how to avoid these problems.
-
-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 @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.
-
-Why not make the user write +127.0 if that’s what is wanted?
-The rationale is that if you are thinking of fixed point
-as a kind of ‘poor man’s floating-point’, then you don’t want
-to be thinking about the scaled integers that are used in its
-representation. Let’s take another example:
-
-@example
-type F2 is delta 2.0**(-15) range -1.0 .. +1.0;
-@end example
-
-Looking at this declaration, it seems casually as though
-it should fit in 16 bits, but again that extra positive value
-+1.0 has the scaled integer equivalent of 2**15 which is one too
-big for signed 16 bits. The implementation can treat this as:
-
-@example
-type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15));
-@end example
-
-and the Ada language design team felt that this was too annoying
-to require. We don’t need to debate this decision at this point,
-since it is well established (the rule about narrowing the ranges
-dates to Ada 83).
-
-But the important point is that an implementation is not required
-to do this narrowing, so we have a potential portability problem.
-We could imagine three types of implementation:
-
-
-@enumerate a
-
-@item 
-those that narrow the range automatically if they can figure
-out that the narrower range will allow storage in a smaller machine unit,
-
-@item 
-those that will narrow only if forced to by a @code{'Size} clause, and
-
-@item 
-those that will never narrow.
-@end enumerate
-
-Now if we are language theoreticians, we can imagine a fourth
-approach: to narrow all the time, e.g. to treat
-
-@example
-type F3 is delta 1.0 range -10.0 .. +23.0;
-@end example
-
-as though it had been written:
-
-@example
-type F3 is delta 1.0 range -9.0 .. +22.0;
-@end example
-
-But although technically allowed, such a behavior would be hostile and silly,
-and no real compiler would do this. All real compilers will fall into one of
-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 @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);
-My_First : constant := -1.0;
-My_Last  : constant := +1.0 - My_Small;
-
-type F2 is delta My_Small range My_First .. My_Last;
-@end example
-
-and then add
-
-@example
-for F2'Small use my_Small;
-for F2'Size  use 16;
-@end example
-
-In practice all compilers will do the same thing here and will give you
-what you want, so the above declarations are fully portable. If you really
-want to play language lawyer and guard against ludicrous behavior by the
-compiler you could add
-
-@example
-Test1 : constant := 1 / Boolean'Pos (F2'First = My_First);
-Test2 : constant := 1 / Boolean'Pos (F2'Last  = My_Last);
-@end example
-
-One or other or both are allowed to be illegal if the compiler is
-behaving in a silly manner, but at least the silly compiler will not
-get away with silently messing with your (very clear) intentions.
-
-If you follow this scheme you will be guaranteed that your fixed-point
-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{442}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{443}
-@section Compatibility with Ada 83
-
-
-@geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012)
-
-Ada 95 and the subsequent revisions Ada 2005 and Ada 2012
-are highly upwards compatible with Ada 83.  In
-particular, the design intention was that the difficulties associated
-with moving from Ada 83 to later versions of the standard should be no greater
-than those that occur when moving from one Ada 83 system to another.
-
-However, there are a number of points at which there are minor
-incompatibilities.  The @cite{Ada 95 Annotated Reference Manual} contains
-full details of these issues as they relate to Ada 95,
-and should be consulted for a complete treatment.
-In practice the
-following subsections treat the most likely issues to be encountered.
-
-@menu
-* Legal Ada 83 programs that are illegal in Ada 95:: 
-* More deterministic semantics:: 
-* Changed semantics:: 
-* Other language compatibility issues:: 
-
-@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{444}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{445}
-@subsection Legal Ada 83 programs that are illegal in Ada 95
-
-
-Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in
-Ada 95 and later versions of the standard:
-
-
-@itemize *
-
-@item 
-`Character literals'
-
-Some uses of character literals are ambiguous.  Since Ada 95 has introduced
-@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:
-
-@example
-for Char in 'A' .. 'Z' loop ... end loop;
-@end example
-
-The problem is that ‘A’ and ‘Z’ could be from either
-@code{Character} or @code{Wide_Character}.  The simplest correction
-is to make the type explicit; e.g.:
-
-@example
-for Char in Character range 'A' .. 'Z' loop ... end loop;
-@end example
-
-@item 
-`New reserved words'
-
-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.
-
-@item 
-`Freezing rules'
-
-The rules in Ada 95 are slightly different with regard to the point at
-which entities are frozen, and representation pragmas and clauses are
-not permitted past the freeze point.  This shows up most typically in
-the form of an error message complaining that a representation item
-appears too late, and the appropriate corrective action is to move
-the item nearer to the declaration of the entity to which it refers.
-
-A particular case is that representation pragmas
-cannot be applied to a subprogram body.  If necessary, a separate subprogram
-declaration must be introduced to which the pragma can be applied.
-
-@item 
-`Optional bodies for library packages'
-
-In Ada 83, a package that did not require a package body was nevertheless
-allowed to have one.  This lead to certain surprises in compiling large
-systems (situations in which the body could be unexpectedly ignored by the
-binder).  In Ada 95, if a package does not require a body then it is not
-permitted to have a body.  To fix this problem, simply remove a redundant
-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 @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 @code{Elaborate_Body} pragma to the package spec,
-since one effect of this pragma is to require the presence of a package body.
-
-@item 
-`Numeric_Error is the same exception as 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
-@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 
-`Indefinite subtypes in generics'
-
-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 @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 @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 @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 id5}@anchor{446}@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{447}
-@subsection More deterministic semantics
-
-
-
-@itemize *
-
-@item 
-`Conversions'
-
-Conversions from real types to integer types round away from 0.  In Ada 83
-the conversion Integer(2.5) could deliver either 2 or 3 as its value.  This
-implementation freedom was intended to support unbiased rounding in
-statistical applications, but in practice it interfered with portability.
-In Ada 95 the conversion semantics are unambiguous, and rounding away from 0
-is required.  Numeric code may be affected by this change in semantics.
-Note, though, that this issue is no worse than already existed in Ada 83
-when porting code from one vendor to another.
-
-@item 
-`Tasking'
-
-The Real-Time Annex introduces a set of policies that define the behavior of
-features that were implementation dependent in Ada 83, such as the order in
-which open select branches are executed.
-@end itemize
-
-@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83
-@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{448}@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{449}
-@subsection Changed semantics
-
-
-The worst kind of incompatibility is one where a program that is legal in
-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
-@code{Character} from 7-bit ASCII to 8-bit Latin-1.
-
-@quotation
-
-@geindex Latin-1
-@end quotation
-
-
-@itemize *
-
-@item 
-`Range of type `@w{`}Character`@w{`}'
-
-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
-@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
-character handling package that may be relevant if code needs to be adapted
-to account for the additional Latin-1 elements.
-The desirable fix is to
-modify the program to accommodate the full character set, but in some cases
-it may be convenient to define a subtype or derived type of Character that
-covers only the restricted range.
-@end itemize
-
-@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83
-@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{44a}@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{44b}
-@subsection Other language compatibility issues
-
-
-
-@itemize *
-
-@item 
-`-gnat83' switch
-
-All implementations of GNAT provide a switch that causes GNAT to operate
-in Ada 83 mode.  In this mode, some but not all compatibility problems
-of the type described above are handled automatically.  For example, the
-new reserved words introduced in Ada 95 and Ada 2005 are treated simply
-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 @code{Compiling Different Versions of Ada} section in
-the @cite{GNAT User’s Guide}.
-
-@item 
-Support for removed Ada 83 pragmas and attributes
-
-A number of pragmas and attributes from Ada 83 were removed from Ada 95,
-generally because they were replaced by other mechanisms.  Ada 95 and Ada 2005
-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 @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{44c}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{44d}
-@section Compatibility between Ada 95 and Ada 2005
-
-
-@geindex Compatibility between Ada 95 and Ada 2005
-
-Although Ada 2005 was designed to be upwards compatible with Ada 95, there are
-a number of incompatibilities. Several are enumerated below;
-for a complete description please see the
-@cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in
-@cite{Rationale for Ada 2005}.
-
-
-@itemize *
-
-@item 
-`New reserved words.'
-
-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.
-
-@item 
-`New declarations in predefined packages.'
-
-A number of packages in the predefined environment contain new declarations:
-@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 
-`Access parameters.'
-
-A nondispatching subprogram with an access parameter cannot be renamed
-as a dispatching operation.  This was permitted in Ada 95.
-
-@item 
-`Access types, discriminants, and constraints.'
-
-Rule changes in this area have led to some incompatibilities; for example,
-constrained subtypes of some access types are not permitted in Ada 2005.
-
-@item 
-`Aggregates for limited types.'
-
-The allowance of aggregates for limited types in Ada 2005 raises the
-possibility of ambiguities in legal Ada 95 programs, since additional types
-now need to be considered in expression resolution.
-
-@item 
-`Fixed-point multiplication and division.'
-
-Certain expressions involving ‘*’ or ‘/’ for a fixed-point type, which
-were legal in Ada 95 and invoked the predefined versions of these operations,
-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
-@code{Standard}.
-
-@item 
-`Return-by-reference types.'
-
-The Ada 95 return-by-reference mechanism has been removed.  Instead, the user
-can declare a function returning a value from an anonymous access type.
-@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 id9}@anchor{44e}@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{44f}
-@section Implementation-dependent characteristics
-
-
-Although the Ada language defines the semantics of each construct as
-precisely as practical, in some situations (for example for reasons of
-efficiency, or where the effect is heavily dependent on the host or target
-platform) the implementation is allowed some freedom.  In porting Ada 83
-code to GNAT, you need to be aware of whether / how the existing code
-exercised such implementation dependencies.  Such characteristics fall into
-several categories, and GNAT offers specific support in assisting the
-transition from certain Ada 83 compilers.
-
-@menu
-* Implementation-defined pragmas:: 
-* Implementation-defined attributes:: 
-* Libraries:: 
-* Elaboration order:: 
-* Target-specific aspects:: 
-
-@end menu
-
-@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics
-@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{450}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{451}
-@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 @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 @code{Use_VADS_Size} may be useful.
-For compatibility with HP Ada 83, GNAT supplies the pragmas
-@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 (@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{452}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{453}
-@subsection Implementation-defined attributes
-
-
-Analogous to pragmas, the set of attributes may be extended by an
-implementation.  All GNAT-defined attributes are described in
-@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 @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 id12}@anchor{454}@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{455}
-@subsection Libraries
-
-
-Vendors may supply libraries to supplement the standard Ada API.  If Ada 83
-code uses vendor-specific libraries then there are several ways to manage
-this in Ada 95 and later versions of the standard:
-
-
-@itemize *
-
-@item 
-If the source code for the libraries (specs and bodies) are
-available, then the libraries can be migrated in the same way as the
-application.
-
-@item 
-If the source code for the specs but not the bodies are
-available, then you can reimplement the bodies.
-
-@item 
-Some features introduced by Ada 95 obviate the need for library support.  For
-example most Ada 83 vendors supplied a package for unsigned integers.  The
-Ada 95 modular type feature is the preferred way to handle this need, so
-instead of migrating or reimplementing the unsigned integer package it may
-be preferable to retrofit the application using modular types.
-@end itemize
-
-@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics
-@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{456}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{457}
-@subsection Elaboration order
-
-
-The implementation can choose any elaboration order consistent with the unit
-dependency relationship.  This freedom means that some orders can result in
-Program_Error being raised due to an ‘Access Before Elaboration’: an attempt
-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 @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 `Elaboration Order Handling in GNAT' appendix
-in the @cite{GNAT User’s Guide}.
-In brief, there are several
-ways to deal with this situation:
-
-
-@itemize *
-
-@item 
-Modify the program to eliminate the circularities, e.g., by moving
-elaboration-time code into explicitly-invoked procedures
-
-@item 
-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 `-gnatE' switch) or locally
-(by selectively suppressing elaboration checks via pragma
-@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 id14}@anchor{458}@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{459}
-@subsection Target-specific aspects
-
-
-Low-level applications need to deal with machine addresses, data
-representations, interfacing with assembler code, and similar issues.  If
-such an Ada 83 application is being ported to different target hardware (for
-example where the byte endianness has changed) then you will need to
-carefully examine the program logic; the porting effort will heavily depend
-on the robustness of the original design.  Moreover, Ada 95 (and thus
-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{45a,,Representation Clauses}.
-
-@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide
-@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{45b}@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{45c}
-@section Compatibility with Other Ada Systems
-
-
-If programs avoid the use of implementation dependent and
-implementation defined features, as documented in the
-@cite{Ada Reference Manual}, there should be a high degree of portability between
-GNAT and other Ada systems.  The following are specific items which
-have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95
-compilers, but do not affect porting code to GNAT.
-(As of January 2007, GNAT is the only compiler available for Ada 2005;
-the following issues may or may not arise for Ada 2005 programs
-when other compilers appear.)
-
-
-@itemize *
-
-@item 
-`Ada 83 Pragmas and Attributes'
-
-Ada 95 compilers are allowed, but not required, to implement the missing
-Ada 83 pragmas and attributes that are no longer defined in Ada 95.
-GNAT implements all such pragmas and attributes, eliminating this as
-a compatibility concern, but some other Ada 95 compilers reject these
-pragmas and attributes.
-
-@item 
-`Specialized Needs Annexes'
-
-GNAT implements the full set of special needs annexes.  At the
-current time, it is the only Ada 95 compiler to do so.  This means that
-programs making use of these features may not be portable to other Ada
-95 compilation systems.
-
-@item 
-`Representation Clauses'
-
-Some other Ada 95 compilers implement only the minimal set of
-representation clauses required by the Ada 95 reference manual.  GNAT goes
-far beyond this minimal set, as described in the next section.
-@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 id16}@anchor{45d}@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{45a}
-@section Representation Clauses
-
-
-The Ada 83 reference manual was quite vague in describing both the minimal
-required implementation of representation clauses, and also their precise
-effects.  Ada 95 (and thus also Ada 2005) are much more explicit, but the
-minimal set of capabilities required is still quite limited.
-
-GNAT implements the full required set of capabilities in
-Ada 95 and Ada 2005, but also goes much further, and in particular
-an effort has been made to be compatible with existing Ada 83 usage to the
-greatest extent possible.
-
-A few cases exist in which Ada 83 compiler behavior is incompatible with
-the requirements in Ada 95 (and thus also Ada 2005).  These are instances of
-intentional or accidental dependence on specific implementation dependent
-characteristics of these Ada 83 compilers.  The following is a list of
-the cases most likely to arise in existing Ada 83 code.
-
-
-@itemize *
-
-@item 
-`Implicit Packing'
-
-Some Ada 83 compilers allowed a Size specification to cause implicit
-packing of an array or record.  This could cause expensive implicit
-conversions for change of representation in the presence of derived
-types, and the Ada design intends to avoid this possibility.
-Subsequent AI’s were issued to make it clear that such implicit
-change of representation in response to a Size clause is inadvisable,
-and this recommendation is represented explicitly in the Ada 95 (and Ada 2005)
-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 @code{Pack}, or for more fine tuned control, provide
-a Component_Size clause.
-
-@item 
-`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 @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
-‘Size attribute when porting Ada 83 code.  The GNAT specific attribute
-Object_Size can provide a useful way of duplicating the behavior of
-some Ada 83 compiler systems.
-
-@item 
-`Size of Access Types'
-
-A common assumption in Ada 83 code is that an access type is in fact a pointer,
-and that therefore it will be the same size as a System.Address value.  This
-assumption is true for GNAT in most cases with one exception.  For the case of
-a pointer to an unconstrained array type (where the bounds may vary from one
-value of the access type to another), the default is to use a ‘fat pointer’,
-which is represented as two separate pointers, one to the bounds, and one to
-the array.  This representation has a number of advantages, including improved
-efficiency.  However, it may cause some difficulties in porting existing Ada 83
-code which makes the assumption that, for example, pointers fit in 32 bits on
-a machine with 32-bit addressing.
-
-To get around this problem, GNAT also permits the use of ‘thin pointers’ for
-access types in this case (where the designated type is an unconstrained array
-type).  These thin pointers are indeed the same size as a System.Address value.
-To specify a thin pointer, use a size clause for the type, for example:
-
-@example
-type X is access all String;
-for X'Size use Standard'Address_Size;
-@end example
-
-which will cause the type X to be represented using a single pointer.
-When using this representation, the bounds are right behind the array.
-This representation is slightly less efficient, and does not allow quite
-such flexibility in the use of foreign pointers or in using the
-Unrestricted_Access attribute to create pointers to non-aliased objects.
-But for any standard portable use of the access type it will work in
-a functionally correct manner and allow porting of existing code.
-Note that another way of forcing a thin pointer representation
-is to use a component size clause for the element size in an array,
-or a record representation clause for an access field in a record.
-
-See the documentation of Unrestricted_Access in the GNAT RM for a
-full discussion of possible problems using this attribute in conjunction
-with thin pointers.
-@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{45e}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{45f}
-@section Compatibility with HP Ada 83
-
-
-All the HP Ada 83 pragmas and attributes are recognized, although only a subset
-of them can sensibly be implemented.  The description of pragmas in
-@ref{7,,Implementation Defined Pragmas} indicates whether or not they are
-applicable to GNAT.
-
-
-@itemize *
-
-@item 
-`Default floating-point representation'
-
-In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83,
-it is VMS format.
-
-@item 
-`System'
-
-the package System in GNAT exactly corresponds to the definition in the
-Ada 95 reference manual, which means that it excludes many of the
-HP Ada 83 extensions.  However, a separate package Aux_DEC is provided
-that contains the additional definitions, and a special pragma,
-Extend_System allows this package to be treated transparently as an
-extension of package System.
-@end itemize
-
-@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top
-@anchor{share/gnu_free_documentation_license doc}@anchor{460}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{461}
-@chapter GNU Free Documentation License
-
-
-Version 1.3, 3 November 2008
-
-Copyright  2000, 2001, 2002, 2007, 2008  Free Software Foundation, Inc
-@indicateurl{https://fsf.org/}
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-
-`Preamble'
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document “free” in the sense of freedom: to
-assure everyone the effective freedom to copy and redistribute it,
-with or without modifying it, either commercially or noncommercially.
-Secondarily, this License preserves for the author and publisher a way
-to get credit for their work, while not being considered responsible
-for modifications made by others.
-
-This License is a kind of “copyleft”, which means that derivative
-works of the document must themselves be free in the same sense.  It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does.  But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book.  We recommend this License
-principally for works whose purpose is instruction or reference.
-
-`1. APPLICABILITY AND DEFINITIONS'
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License.  Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein.  The `Document', below,
-refers to any such manual or work.  Any member of the public is a
-licensee, and is addressed as “`you'”.  You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-A “`Modified Version'” of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A “`Secondary Section'” is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document’s overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject.  (Thus, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.)  The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The “`Invariant Sections'” are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License.  If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant.  The Document may contain zero
-Invariant Sections.  If the Document does not identify any Invariant
-Sections then there are none.
-
-The “`Cover Texts'” are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License.  A Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A “`Transparent'” copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters.  A copy made in an otherwise Transparent file
-format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text.  A copy that is not “Transparent” is called `Opaque'.
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML, PostScript or PDF designed for human modification.  Examples of
-transparent image formats include PNG, XCF and JPG.  Opaque formats
-include proprietary formats that can be read and edited only by
-proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated HTML, PostScript or PDF produced by some word
-processors for output purposes only.
-
-The “`Title Page'” means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page.  For works in
-formats which do not have any title page as such, “Title Page” means
-the text near the most prominent appearance of the work’s title,
-preceding the beginning of the body of the text.
-
-The “`publisher'” means any person or entity that distributes
-copies of the Document to the public.
-
-A section “`Entitled XYZ'” means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language.  (Here XYZ stands for a
-specific section name mentioned below, such as “`Acknowledgements'”,
-“`Dedications'”, “`Endorsements'”, or “`History'”.)
-To “`Preserve the Title'”
-of such a section when you modify the Document means that it remains a
-section “Entitled XYZ” according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document.  These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-
-`2. VERBATIM COPYING'
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License.  You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute.  However, you may accept
-compensation in exchange for copies.  If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
-`3. COPYING IN QUANTITY'
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) of the Document, numbering more than 100, and the
-Document’s license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover.  Both covers must also clearly and legibly identify
-you as the publisher of these copies.  The front cover must present
-the full title with all words of the title equally prominent and
-visible.  You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-If you use the latter option, you must take reasonably prudent steps,
-when you begin distribution of Opaque copies in quantity, to ensure
-that this Transparent copy will remain thus accessible at the stated
-location until at least one year after the last time you distribute an
-Opaque copy (directly or through your agents or retailers) of that
-edition to the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
-`4. MODIFICATIONS'
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it.  In addition, you must do these things in the Modified Version:
-
-
-@enumerate A
-
-@item 
-Use in the Title Page (and on the covers, if any) a title distinct
-from that of the Document, and from those of previous versions
-(which should, if there were any, be listed in the History section
-of the Document).  You may use the same title as a previous version
-if the original publisher of that version gives permission.
-
-@item 
-List on the Title Page, as authors, one or more persons or entities
-responsible for authorship of the modifications in the Modified
-Version, together with at least five of the principal authors of the
-Document (all of its principal authors, if it has fewer than five),
-unless they release you from this requirement.
-
-@item 
-State on the Title page the name of the publisher of the
-Modified Version, as the publisher.
-
-@item 
-Preserve all the copyright notices of the Document.
-
-@item 
-Add an appropriate copyright notice for your modifications
-adjacent to the other copyright notices.
-
-@item 
-Include, immediately after the copyright notices, a license notice
-giving the public permission to use the Modified Version under the
-terms of this License, in the form shown in the Addendum below.
-
-@item 
-Preserve in that license notice the full lists of Invariant Sections
-and required Cover Texts given in the Document’s license notice.
-
-@item 
-Include an unaltered copy of this License.
-
-@item 
-Preserve the section Entitled “History”, Preserve its Title, and add
-to it an item stating at least the title, year, new authors, and
-publisher of the Modified Version as given on the Title Page.  If
-there is no section Entitled “History” in the Document, create one
-stating the title, year, authors, and publisher of the Document as
-given on its Title Page, then add an item describing the Modified
-Version as stated in the previous sentence.
-
-@item 
-Preserve the network location, if any, given in the Document for
-public access to a Transparent copy of the Document, and likewise
-the network locations given in the Document for previous versions
-it was based on.  These may be placed in the “History” section.
-You may omit a network location for a work that was published at
-least four years before the Document itself, or if the original
-publisher of the version it refers to gives permission.
-
-@item 
-For any section Entitled “Acknowledgements” or “Dedications”,
-Preserve the Title of the section, and preserve in the section all
-the substance and tone of each of the contributor acknowledgements
-and/or dedications given therein.
-
-@item 
-Preserve all the Invariant Sections of the Document,
-unaltered in their text and in their titles.  Section numbers
-or the equivalent are not considered part of the section titles.
-
-@item 
-Delete any section Entitled “Endorsements”.  Such a section
-may not be included in the Modified Version.
-
-@item 
-Do not retitle any existing section to be Entitled “Endorsements”
-or to conflict in title with any Invariant Section.
-
-@item 
-Preserve any Warranty Disclaimers.
-@end enumerate
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant.  To do this, add their titles to the
-list of Invariant Sections in the Modified Version’s license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section Entitled “Endorsements”, provided it contains
-nothing but endorsements of your Modified Version by various
-parties—for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version.  Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity.  If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
-`5. COMBINING DOCUMENTS'
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice, and that you preserve all their Warranty Disclaimers.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy.  If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled “History”
-in the various original documents, forming one section Entitled
-“History”; likewise combine any sections Entitled “Acknowledgements”,
-and any sections Entitled “Dedications”.  You must delete all sections
-Entitled “Endorsements”.
-
-`6. COLLECTIONS OF DOCUMENTS'
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
-`7. AGGREGATION WITH INDEPENDENT WORKS'
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, is called an “aggregate” if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation’s users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which are not themselves
-derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one half of
-the entire aggregate, the Document’s Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-
-`8. TRANSLATION'
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections.  You may include a
-translation of this License, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers.  In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled “Acknowledgements”,
-“Dedications”, or “History”, the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-
-`9. TERMINATION'
-
-You may not copy, modify, sublicense, or distribute the Document
-except as expressly provided under this License.  Any attempt
-otherwise to copy, modify, sublicense, or distribute it is void, and
-will automatically terminate your rights under this License.
-
-However, if you cease all violation of this License, then your license
-from a particular copyright holder is reinstated (a) provisionally,
-unless and until the copyright holder explicitly and finally
-terminates your license, and (b) permanently, if the copyright holder
-fails to notify you of the violation by some reasonable means prior to
-60 days after the cessation.
-
-Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, receipt of a copy of some or all of the same material does
-not give you any rights to use it.
-
-`10. FUTURE REVISIONS OF THIS LICENSE'
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time.  Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.  See
-@indicateurl{https://www.gnu.org/copyleft/}.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License “or any later version” applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation.  If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.  If the Document
-specifies that a proxy can decide which future versions of this
-License can be used, that proxy’s public statement of acceptance of a
-version permanently authorizes you to choose that version for the
-Document.
-
-`11. RELICENSING'
-
-“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
-World Wide Web server that publishes copyrightable works and also
-provides prominent facilities for anybody to edit those works.  A
-public wiki that anybody can edit is an example of such a server.  A
-“Massive Multiauthor Collaboration” (or “MMC”) contained in the
-site means any set of copyrightable works thus published on the MMC
-site.
-
-“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
-license published by Creative Commons Corporation, a not-for-profit
-corporation with a principal place of business in San Francisco,
-California, as well as future copyleft versions of that license
-published by that same organization.
-
-“Incorporate” means to publish or republish a Document, in whole or
-in part, as part of another Document.
-
-An MMC is “eligible for relicensing” if it is licensed under this
-License, and if all works that were first published under this License
-somewhere other than this MMC, and subsequently incorporated in whole
-or in part into the MMC, (1) had no cover texts or invariant sections,
-and (2) were thus incorporated prior to November 1, 2008.
-
-The operator of an MMC Site may republish an MMC contained in the site
-under CC-BY-SA on the same site at any time before August 1, 2009,
-provided the MMC is eligible for relicensing.
-
-`ADDENDUM: How to use this License for your documents'
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
-@quotation
-
-Copyright © YEAR  YOUR NAME.
-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, no Front-Cover Texts, and no Back-Cover Texts.
-A copy of the license is included in the section entitled “GNU
-Free Documentation License”.
-@end quotation
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the “with … Texts.” line with this:
-
-@quotation
-
-with the Invariant Sections being LIST THEIR TITLES, with the
-Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-@end quotation
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
-@node Index,,GNU Free Documentation License,Top
-@unnumbered Index
-
-
-@printindex ge
-
-
-@c %**end of body
-@bye

diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
deleted file mode 100644 (file)
index 7b1aaeb..0000000
--- a/gcc/ada/gnat_ugn.texi
+++ /dev/null
@@ -1,29389 +0,0 @@
-\input texinfo   @c -*-texinfo-*-
-@c %**start of header
-@setfilename gnat_ugn.info
-@documentencoding UTF-8
-@ifinfo
-@*Generated by Sphinx 5.2.3.@*
-@end ifinfo
-@settitle GNAT User's Guide for Native Platforms
-@defindex ge
-@paragraphindent 0
-@exampleindent 4
-@finalout
-@dircategory GNU Ada Tools 
-@direntry
-* gnat_ugn: (gnat_ugn.info). gnat_ugn
-@end direntry
-
-@c %**end of header
-
-@copying
-@quotation
-GNAT User's Guide for Native Platforms , Oct 27, 2022
-
-AdaCore
-
-Copyright @copyright{} 2008-2022, Free Software Foundation
-@end quotation
-
-@end copying
-
-@titlepage
-@title GNAT User's Guide for Native Platforms
-@insertcopying
-@end titlepage
-@contents
-
-@c %** start of user preamble
-
-@c %** end of user preamble
-
-@ifnottex
-@node Top
-@top GNAT User's Guide for Native Platforms
-@insertcopying
-@end ifnottex
-
-@c %**start of body
-@anchor{gnat_ugn doc}@anchor{0}
-`GNAT, The GNU Ada Development Environment'
-
-
-@include gcc-common.texi
-GCC version @value{version-GCC}@*
-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{1,,GNU Free Documentation License}.
-
-@menu
-* About This Guide:: 
-* Getting Started with GNAT:: 
-* The GNAT Compilation Model:: 
-* Building Executable Programs with GNAT:: 
-* GNAT Utility Programs:: 
-* GNAT and Program Execution:: 
-* Platform-Specific Information:: 
-* Example of Binder Output File:: 
-* Elaboration Order Handling in GNAT:: 
-* Inline Assembler:: 
-* GNU Free Documentation License:: 
-* Index:: 
-
-@detailmenu
- --- The Detailed Node Listing ---
-
-About This Guide
-
-* What This Guide Contains:: 
-* What You Should Know before Reading This Guide:: 
-* Related Information:: 
-* Conventions:: 
-
-Getting Started with GNAT
-
-* System Requirements:: 
-* Running GNAT:: 
-* Running a Simple Ada Program:: 
-* Running a Program with Multiple Units:: 
-
-The GNAT Compilation Model
-
-* Source Representation:: 
-* Foreign Language Representation:: 
-* File Naming Topics and Utilities:: 
-* Configuration Pragmas:: 
-* Generating Object Files:: 
-* Source Dependencies:: 
-* The Ada Library Information Files:: 
-* Binding an Ada Program:: 
-* GNAT and Libraries:: 
-* Conditional Compilation:: 
-* Mixed Language Programming:: 
-* GNAT and Other Compilation Models:: 
-* Using GNAT Files with External Tools:: 
-
-Foreign Language Representation
-
-* Latin-1:: 
-* Other 8-Bit Codes:: 
-* Wide_Character Encodings:: 
-* Wide_Wide_Character Encodings:: 
-
-File Naming Topics and Utilities
-
-* File Naming Rules:: 
-* Using Other File Names:: 
-* Alternative File Naming Schemes:: 
-* Handling Arbitrary File Naming Conventions with gnatname:: 
-* File Name Krunching with gnatkr:: 
-* Renaming Files with gnatchop:: 
-
-Handling Arbitrary File Naming Conventions with gnatname
-
-* Arbitrary File Naming Conventions:: 
-* Running gnatname:: 
-* Switches for gnatname:: 
-* Examples of gnatname Usage:: 
-
-File Name Krunching with gnatkr
-
-* About gnatkr:: 
-* Using gnatkr:: 
-* Krunching Method:: 
-* Examples of gnatkr Usage:: 
-
-Renaming Files with gnatchop
-
-* Handling Files with Multiple Units:: 
-* Operating gnatchop in Compilation Mode:: 
-* Command Line for gnatchop:: 
-* Switches for gnatchop:: 
-* Examples of gnatchop Usage:: 
-
-Configuration Pragmas
-
-* Handling of Configuration Pragmas:: 
-* The Configuration Pragmas Files:: 
-
-GNAT and Libraries
-
-* Introduction to Libraries in GNAT:: 
-* General Ada Libraries:: 
-* Stand-alone Ada Libraries:: 
-* Rebuilding the GNAT Run-Time Library:: 
-
-General Ada Libraries
-
-* Building a library:: 
-* Installing a library:: 
-* Using a library:: 
-
-Stand-alone Ada Libraries
-
-* Introduction to Stand-alone Libraries:: 
-* Building a Stand-alone Library:: 
-* Creating a Stand-alone Library to be used in a non-Ada context:: 
-* Restrictions in Stand-alone Libraries:: 
-
-Conditional Compilation
-
-* Modeling Conditional Compilation in Ada:: 
-* Preprocessing with gnatprep:: 
-* Integrated Preprocessing:: 
-
-Modeling Conditional Compilation in Ada
-
-* Use of Boolean Constants:: 
-* Debugging - A Special Case:: 
-* Conditionalizing Declarations:: 
-* Use of Alternative Implementations:: 
-* Preprocessing:: 
-
-Preprocessing with gnatprep
-
-* Preprocessing Symbols:: 
-* Using gnatprep:: 
-* Switches for gnatprep:: 
-* Form of Definitions File:: 
-* Form of Input Text for gnatprep:: 
-
-Mixed Language Programming
-
-* Interfacing to C:: 
-* Calling Conventions:: 
-* Building Mixed Ada and C++ Programs:: 
-* Generating Ada Bindings for C and C++ headers:: 
-* Generating C Headers for Ada Specifications:: 
-
-Building Mixed Ada and C++ Programs
-
-* Interfacing to C++:: 
-* Linking a Mixed C++ & Ada Program:: 
-* A Simple Example:: 
-* Interfacing with C++ constructors:: 
-* Interfacing with C++ at the Class Level:: 
-
-Generating Ada Bindings for C and C++ headers
-
-* Running the Binding Generator:: 
-* Generating Bindings for C++ Headers:: 
-* Switches:: 
-
-Generating C Headers for Ada Specifications
-
-* Running the C Header Generator:: 
-
-GNAT and Other Compilation Models
-
-* Comparison between GNAT and C/C++ Compilation Models:: 
-* Comparison between GNAT and Conventional Ada Library Models:: 
-
-Using GNAT Files with External Tools
-
-* Using Other Utility Programs with GNAT:: 
-* The External Symbol Naming Scheme of GNAT:: 
-
-Building Executable Programs with GNAT
-
-* Building with gnatmake:: 
-* Compiling with gcc:: 
-* Compiler Switches:: 
-* Linker Switches:: 
-* Binding with gnatbind:: 
-* Linking with gnatlink:: 
-* Using the GNU make Utility:: 
-
-Building with gnatmake
-
-* Running gnatmake:: 
-* Switches for gnatmake:: 
-* Mode Switches for gnatmake:: 
-* Notes on the Command Line:: 
-* How gnatmake Works:: 
-* Examples of gnatmake Usage:: 
-
-Compiling with gcc
-
-* Compiling Programs:: 
-* Search Paths and the Run-Time Library (RTL): Search Paths and the Run-Time Library RTL. 
-* Order of Compilation Issues:: 
-* Examples:: 
-
-Compiler Switches
-
-* Alphabetical List of All Switches:: 
-* Output and Error Message Control:: 
-* Warning Message Control:: 
-* Debugging and Assertion Control:: 
-* Validity Checking:: 
-* Style Checking:: 
-* Run-Time Checks:: 
-* Using gcc for Syntax Checking:: 
-* Using gcc for Semantic Checking:: 
-* Compiling Different Versions of Ada:: 
-* Character Set Control:: 
-* File Naming Control:: 
-* Subprogram Inlining Control:: 
-* Auxiliary Output Control:: 
-* Debugging Control:: 
-* Exception Handling Control:: 
-* Units to Sources Mapping Files:: 
-* Code Generation Control:: 
-
-Binding with gnatbind
-
-* Running gnatbind:: 
-* Switches for gnatbind:: 
-* Command-Line Access:: 
-* Search Paths for gnatbind:: 
-* Examples of gnatbind Usage:: 
-
-Switches for gnatbind
-
-* Consistency-Checking Modes:: 
-* Binder Error Message Control:: 
-* Elaboration Control:: 
-* Output Control:: 
-* Dynamic Allocation Control:: 
-* Binding with Non-Ada Main Programs:: 
-* Binding Programs with No Main Subprogram:: 
-
-Linking with gnatlink
-
-* Running gnatlink:: 
-* Switches for gnatlink:: 
-
-Using the GNU make Utility
-
-* Using gnatmake in a Makefile:: 
-* Automatically Creating a List of Directories:: 
-* Generating the Command Line Switches:: 
-* Overcoming Command Line Length Limits:: 
-
-GNAT Utility Programs
-
-* The File Cleanup Utility gnatclean:: 
-* The GNAT Library Browser gnatls:: 
-
-The File Cleanup Utility gnatclean
-
-* Running gnatclean:: 
-* Switches for gnatclean:: 
-
-The GNAT Library Browser gnatls
-
-* Running gnatls:: 
-* Switches for gnatls:: 
-* Example of gnatls Usage:: 
-
-GNAT and Program Execution
-
-* Running and Debugging Ada Programs:: 
-* Profiling:: 
-* Improving Performance:: 
-* Overflow Check Handling in GNAT:: 
-* Performing Dimensionality Analysis in GNAT:: 
-* Stack Related Facilities:: 
-* Memory Management Issues:: 
-
-Running and Debugging Ada Programs
-
-* The GNAT Debugger GDB:: 
-* Running GDB:: 
-* Introduction to GDB Commands:: 
-* Using Ada Expressions:: 
-* Calling User-Defined Subprograms:: 
-* Using the next Command in a Function:: 
-* Stopping When Ada Exceptions Are Raised:: 
-* Ada Tasks:: 
-* Debugging Generic Units:: 
-* Remote Debugging with gdbserver:: 
-* GNAT Abnormal Termination or Failure to Terminate:: 
-* Naming Conventions for GNAT Source Files:: 
-* Getting Internal Debugging Information:: 
-* Stack Traceback:: 
-* Pretty-Printers for the GNAT runtime:: 
-
-Stack Traceback
-
-* Non-Symbolic Traceback:: 
-* Symbolic Traceback:: 
-
-Profiling
-
-* Profiling an Ada Program with gprof:: 
-
-Profiling an Ada Program with gprof
-
-* Compilation for profiling:: 
-* Program execution:: 
-* Running gprof:: 
-* Interpretation of profiling results:: 
-
-Improving Performance
-
-* Performance Considerations:: 
-* Text_IO Suggestions:: 
-* Reducing Size of Executables with Unused Subprogram/Data Elimination:: 
-
-Performance Considerations
-
-* Controlling Run-Time Checks:: 
-* Use of Restrictions:: 
-* Optimization Levels:: 
-* Debugging Optimized Code:: 
-* Inlining of Subprograms:: 
-* Floating Point Operations:: 
-* Vectorization of loops:: 
-* Other Optimization Switches:: 
-* Optimization and Strict Aliasing:: 
-* Aliased Variables and Optimization:: 
-* Atomic Variables and Optimization:: 
-* Passive Task Optimization:: 
-
-Reducing Size of Executables with Unused Subprogram/Data Elimination
-
-* About unused subprogram/data elimination:: 
-* Compilation options:: 
-* Example of unused subprogram/data elimination:: 
-
-Overflow Check Handling in GNAT
-
-* Background:: 
-* Management of Overflows in GNAT:: 
-* Specifying the Desired Mode:: 
-* Default Settings:: 
-* Implementation Notes:: 
-
-Stack Related Facilities
-
-* Stack Overflow Checking:: 
-* Static Stack Usage Analysis:: 
-* Dynamic Stack Usage Analysis:: 
-
-Memory Management Issues
-
-* Some Useful Memory Pools:: 
-* The GNAT Debug Pool Facility:: 
-
-Platform-Specific Information
-
-* Run-Time Libraries:: 
-* Specifying a Run-Time Library:: 
-* GNU/Linux Topics:: 
-* Microsoft Windows Topics:: 
-* Mac OS Topics:: 
-
-Run-Time Libraries
-
-* Summary of Run-Time Configurations:: 
-
-Specifying a Run-Time Library
-
-* Choosing the Scheduling Policy:: 
-
-GNU/Linux Topics
-
-* Required Packages on GNU/Linux:: 
-* A GNU/Linux Debug Quirk:: 
-
-Microsoft Windows Topics
-
-* Using GNAT on Windows:: 
-* Using a network installation of GNAT:: 
-* CONSOLE and WINDOWS subsystems:: 
-* Temporary Files:: 
-* Disabling Command Line Argument Expansion:: 
-* Windows Socket Timeouts:: 
-* Mixed-Language Programming on Windows:: 
-* Windows Specific Add-Ons:: 
-
-Mixed-Language Programming on Windows
-
-* Windows Calling Conventions:: 
-* Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs. 
-* Using DLLs with GNAT:: 
-* Building DLLs with GNAT Project files:: 
-* Building DLLs with GNAT:: 
-* Building DLLs with gnatdll:: 
-* Ada DLLs and Finalization:: 
-* Creating a Spec for Ada DLLs:: 
-* GNAT and Windows Resources:: 
-* Using GNAT DLLs from Microsoft Visual Studio Applications:: 
-* Debugging a DLL:: 
-* Setting Stack Size from gnatlink:: 
-* Setting Heap Size from gnatlink:: 
-
-Windows Calling Conventions
-
-* C Calling Convention:: 
-* Stdcall Calling Convention:: 
-* Win32 Calling Convention:: 
-* DLL Calling Convention:: 
-
-Using DLLs with GNAT
-
-* Creating an Ada Spec for the DLL Services:: 
-* Creating an Import Library:: 
-
-Building DLLs with gnatdll
-
-* Limitations When Using Ada DLLs from Ada:: 
-* Exporting Ada Entities:: 
-* Ada DLLs and Elaboration:: 
-
-Creating a Spec for Ada DLLs
-
-* Creating the Definition File:: 
-* Using gnatdll:: 
-
-GNAT and Windows Resources
-
-* Building Resources:: 
-* Compiling Resources:: 
-* Using Resources:: 
-
-Debugging a DLL
-
-* Program and DLL Both Built with GCC/GNAT:: 
-* Program Built with Foreign Tools and DLL Built with GCC/GNAT:: 
-
-Windows Specific Add-Ons
-
-* Win32Ada:: 
-* wPOSIX:: 
-
-Mac OS Topics
-
-* Codesigning the Debugger:: 
-
-Elaboration Order Handling in GNAT
-
-* Elaboration Code:: 
-* Elaboration Order:: 
-* Checking the Elaboration Order:: 
-* Controlling the Elaboration Order in Ada:: 
-* Controlling the Elaboration Order in GNAT:: 
-* Mixing Elaboration Models:: 
-* ABE Diagnostics:: 
-* SPARK Diagnostics:: 
-* Elaboration Circularities:: 
-* Resolving Elaboration Circularities:: 
-* Elaboration-related Compiler Switches:: 
-* Summary of Procedures for Elaboration Control:: 
-* Inspecting the Chosen Elaboration Order:: 
-
-Inline Assembler
-
-* Basic Assembler Syntax:: 
-* A Simple Example of Inline Assembler:: 
-* Output Variables in Inline Assembler:: 
-* Input Variables in Inline Assembler:: 
-* Inlining Inline Assembler Code:: 
-* Other Asm Functionality:: 
-
-Other Asm Functionality
-
-* The Clobber Parameter:: 
-* The Volatile Parameter:: 
-
-@end detailmenu
-@end menu
-
-@node About This Guide,Getting Started with GNAT,Top,Top
-@anchor{gnat_ugn/about_this_guide doc}@anchor{2}@anchor{gnat_ugn/about_this_guide about-this-guide}@anchor{3}@anchor{gnat_ugn/about_this_guide gnat-user-s-guide-for-native-platforms}@anchor{4}@anchor{gnat_ugn/about_this_guide id1}@anchor{5}
-@chapter About This Guide
-
-
-
-This guide describes the use of GNAT,
-a compiler and software development
-toolset for the full Ada programming language.
-It documents the features of the compiler and tools, and explains
-how to use them to build Ada applications.
-
-GNAT implements Ada 95, Ada 2005, Ada 2012, and Ada 202x, and it may also be
-invoked in Ada 83 compatibility mode.
-By default, GNAT assumes Ada 2012, but you can override with a
-compiler switch (@ref{6,,Compiling Different Versions of Ada})
-to explicitly specify the language version.
-Throughout this manual, references to ‘Ada’ without a year suffix
-apply to all Ada versions of the language, starting with Ada 95.
-
-@menu
-* What This Guide Contains:: 
-* What You Should Know before Reading This Guide:: 
-* Related Information:: 
-* Conventions:: 
-
-@end menu
-
-@node What This Guide Contains,What You Should Know before Reading This Guide,,About This Guide
-@anchor{gnat_ugn/about_this_guide what-this-guide-contains}@anchor{7}
-@section What This Guide Contains
-
-
-This guide contains the following chapters:
-
-
-@itemize *
-
-@item 
-@ref{8,,Getting Started with GNAT} describes how to get started compiling
-and running Ada programs with the GNAT Ada programming environment.
-
-@item 
-@ref{9,,The GNAT Compilation Model} describes the compilation model used
-by GNAT.
-
-@item 
-@ref{a,,Building Executable Programs with GNAT} describes how to use the
-main GNAT tools to build executable programs, and it also gives examples of
-using the GNU make utility with GNAT.
-
-@item 
-@ref{b,,GNAT Utility Programs} explains the various utility programs that
-are included in the GNAT environment
-
-@item 
-@ref{c,,GNAT and Program Execution} covers a number of topics related to
-running, debugging, and tuning the performace of programs developed
-with GNAT
-@end itemize
-
-Appendices cover several additional topics:
-
-
-@itemize *
-
-@item 
-@ref{d,,Platform-Specific Information} describes the different run-time
-library implementations and also presents information on how to use
-GNAT on several specific platforms
-
-@item 
-@ref{e,,Example of Binder Output File} shows the source code for the binder
-output file for a sample program.
-
-@item 
-@ref{f,,Elaboration Order Handling in GNAT} describes how GNAT helps
-you deal with elaboration order issues.
-
-@item 
-@ref{10,,Inline Assembler} shows how to use the inline assembly facility
-in an Ada program.
-@end itemize
-
-@node What You Should Know before Reading This Guide,Related Information,What This Guide Contains,About This Guide
-@anchor{gnat_ugn/about_this_guide what-you-should-know-before-reading-this-guide}@anchor{11}
-@section What You Should Know before Reading This Guide
-
-
-@geindex Ada 95 Language Reference Manual
-
-@geindex Ada 2005 Language Reference Manual
-
-This guide assumes a basic familiarity with the Ada 95 language, as
-described in the International Standard ANSI/ISO/IEC-8652:1995, January
-1995.
-Reference manuals for Ada 95, Ada 2005, and Ada 2012 are included in
-the GNAT documentation package.
-
-@node Related Information,Conventions,What You Should Know before Reading This Guide,About This Guide
-@anchor{gnat_ugn/about_this_guide related-information}@anchor{12}
-@section Related Information
-
-
-For further information about Ada and related tools, please refer to the
-following documents:
-
-
-@itemize *
-
-@item 
-@cite{Ada 95 Reference Manual}, @cite{Ada 2005 Reference Manual}, and
-@cite{Ada 2012 Reference Manual}, which contain reference
-material for the several revisions of the Ada language standard.
-
-@item 
-@cite{GNAT Reference_Manual}, which contains all reference material for the GNAT
-implementation of Ada.
-
-@item 
-@cite{Using GNAT Studio}, which describes the GNAT Studio
-Integrated Development Environment.
-
-@item 
-@cite{GNAT Studio Tutorial}, which introduces the
-main GNAT Studio features through examples.
-
-@item 
-@cite{Debugging with GDB},
-for all details on the use of the GNU source-level debugger.
-
-@item 
-@cite{GNU Emacs Manual},
-for full information on the extensible editor and programming
-environment Emacs.
-@end itemize
-
-@node Conventions,,Related Information,About This Guide
-@anchor{gnat_ugn/about_this_guide conventions}@anchor{13}
-@section Conventions
-
-
-@geindex Conventions
-@geindex typographical
-
-@geindex Typographical conventions
-
-Following are examples of the typographical and graphic conventions used
-in this guide:
-
-
-@itemize *
-
-@item 
-@code{Functions}, @code{utility program names}, @code{standard names},
-and @code{classes}.
-
-@item 
-@code{Option flags}
-
-@item 
-@code{File names}
-
-@item 
-@code{Variables}
-
-@item 
-`Emphasis'
-
-@item 
-[optional information or parameters]
-
-@item 
-Examples are described by text
-
-@example
-and then shown this way.
-@end example
-
-@item 
-Commands that are entered by the user are shown as preceded by a prompt string
-comprising the @code{$} character followed by a space.
-
-@item 
-Full file names are shown with the ‘/’ character
-as the directory separator; e.g., @code{parent-dir/subdir/myfile.adb}.
-If you are using GNAT on a Windows platform, please note that
-the ‘\’ character should be used instead.
-@end itemize
-
-@node Getting Started with GNAT,The GNAT Compilation Model,About This Guide,Top
-@anchor{gnat_ugn/getting_started_with_gnat doc}@anchor{14}@anchor{gnat_ugn/getting_started_with_gnat getting-started-with-gnat}@anchor{8}@anchor{gnat_ugn/getting_started_with_gnat id1}@anchor{15}
-@chapter Getting Started with GNAT
-
-
-This chapter describes how to use GNAT’s command line interface to build
-executable Ada programs.
-On most platforms a visually oriented Integrated Development Environment
-is also available: GNAT Studio.
-GNAT Studio offers a graphical “look and feel”, support for development in
-other programming languages, comprehensive browsing features, and
-many other capabilities.
-For information on GNAT Studio please refer to the
-@cite{GNAT Studio documentation}.
-
-@menu
-* System Requirements:: 
-* Running GNAT:: 
-* Running a Simple Ada Program:: 
-* Running a Program with Multiple Units:: 
-
-@end menu
-
-@node System Requirements,Running GNAT,,Getting Started with GNAT
-@anchor{gnat_ugn/getting_started_with_gnat id2}@anchor{16}@anchor{gnat_ugn/getting_started_with_gnat system-requirements}@anchor{17}
-@section System Requirements
-
-
-Even though any machine can run the GNAT toolset and GNAT Studio IDE, in order
-to get the best experience, we recommend using a machine with as many cores
-as possible since all individual compilations can run in parallel.
-A comfortable setup for a compiler server is a machine with 24 physical cores
-or more, with at least 48 GB of memory (2 GB per core).
-
-For a desktop machine, a minimum of 4 cores is recommended (8 preferred),
-with at least 2GB per core (so 8 to 16GB).
-
-In addition, for running and navigating sources in GNAT Studio smoothly, we
-recommend at least 1.5 GB plus 3 GB of RAM per 1 million source line of code.
-In other words, we recommend at least 3 GB for for 500K lines of code and
-7.5 GB for 2 million lines of code.
-
-Note that using local and fast drives will also make a difference in terms of
-build and link time. Network drives such as NFS, SMB, or worse, configuration
-management filesystems (such as ClearCase dynamic views) should be avoided as
-much as possible and will produce very degraded performance (typically 2 to 3
-times slower than on local fast drives). If such slow drives cannot be avoided
-for accessing the source code, then you should at least configure your project
-file so that the result of the compilation is stored on a drive local to the
-machine performing the run. This can be achieved by setting the @code{Object_Dir}
-project file attribute.
-
-@node Running GNAT,Running a Simple Ada Program,System Requirements,Getting Started with GNAT
-@anchor{gnat_ugn/getting_started_with_gnat id3}@anchor{18}@anchor{gnat_ugn/getting_started_with_gnat running-gnat}@anchor{19}
-@section Running GNAT
-
-
-Three steps are needed to create an executable file from an Ada source
-file:
-
-
-@itemize *
-
-@item 
-The source file(s) must be compiled.
-
-@item 
-The file(s) must be bound using the GNAT binder.
-
-@item 
-All appropriate object files must be linked to produce an executable.
-@end itemize
-
-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.
-
-@node Running a Simple Ada Program,Running a Program with Multiple Units,Running GNAT,Getting Started with GNAT
-@anchor{gnat_ugn/getting_started_with_gnat id4}@anchor{1a}@anchor{gnat_ugn/getting_started_with_gnat running-a-simple-ada-program}@anchor{1b}
-@section Running a Simple Ada Program
-
-
-Any text editor may be used to prepare an Ada program.
-(If Emacs is used, the optional Ada mode may be helpful in laying out the
-program.)
-The program text is a normal text file. We will assume in our initial
-example that you have used your editor to prepare the following
-standard format text file:
-
-@example
-with Ada.Text_IO; use Ada.Text_IO;
-procedure Hello is
-begin
-   Put_Line ("Hello WORLD!");
-end Hello;
-@end example
-
-This file should be named @code{hello.adb}.
-With the normal default file naming conventions, GNAT requires
-that each file
-contain a single compilation unit whose file name is the
-unit name,
-with periods replaced by hyphens; the
-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 @code{Source_File_Name} (for further information please
-see @ref{1c,,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 @code{gnatchop} utility
-can be used to generate correctly-named source files
-(see @ref{1d,,Renaming Files with gnatchop}).
-
-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
-
-@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 @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.)
-
-This compile command generates a file
-@code{hello.o}, which is the object
-file corresponding to your Ada program. It also generates
-an ‘Ada Library Information’ file @code{hello.ali},
-which contains additional information used to check
-that an Ada program is consistent.
-
-To build an executable file, use either @code{gnatmake} or gprbuild with
-the name of the main file: these tools are builders that will take care of
-all the necessary build steps in the correct order.
-In particular, these builders automatically recompile 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 `@w{`}gnatmake`@w{`})
-
-@example
-$ gnatmake hello.adb
-@end example
-
-The result is an executable program called @code{hello}, which can be
-run by entering:
-
-@example
-$ hello
-@end example
-
-assuming that the current directory is on the search path
-for executable programs.
-
-and, if all has gone well, you will see:
-
-@example
-Hello WORLD!
-@end example
-
-appear in response to this command.
-
-@node Running a Program with Multiple Units,,Running a Simple Ada Program,Getting Started with GNAT
-@anchor{gnat_ugn/getting_started_with_gnat id5}@anchor{1e}@anchor{gnat_ugn/getting_started_with_gnat running-a-program-with-multiple-units}@anchor{1f}
-@section Running a Program with Multiple Units
-
-
-Consider a slightly more complicated example that has three files: a
-main program, and the spec and body of a package:
-
-@example
-package Greetings is
-   procedure Hello;
-   procedure Goodbye;
-end Greetings;
-
-with Ada.Text_IO; use Ada.Text_IO;
-package body Greetings is
-   procedure Hello is
-   begin
-      Put_Line ("Hello WORLD!");
-   end Hello;
-
-   procedure Goodbye is
-   begin
-      Put_Line ("Goodbye WORLD!");
-   end Goodbye;
-end Greetings;
-
-with Greetings;
-procedure Gmain is
-begin
-   Greetings.Hello;
-   Greetings.Goodbye;
-end Gmain;
-@end example
-
-Following the one-unit-per-file rule, place this program in the
-following three separate files:
-
-
-@table @asis
-
-@item `greetings.ads'
-
-spec of package @code{Greetings}
-
-@item `greetings.adb'
-
-body of package @code{Greetings}
-
-@item `gmain.adb'
-
-body of main program
-@end table
-
-Note that there is no required order of compilation when using GNAT.
-In particular it is perfectly fine to compile the main program first.
-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 @code{-gnatc} switch:
-
-@example
-$ gcc -c greetings.ads -gnatc
-@end example
-
-Although the compilation can be done in separate steps, in practice it is
-almost always more convenient to use the @code{gnatmake} or @code{gprbuild} tools:
-
-@example
-$ gnatmake gmain.adb
-@end example
-
-@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
-
-@node The GNAT Compilation Model,Building Executable Programs with GNAT,Getting Started with GNAT,Top
-@anchor{gnat_ugn/the_gnat_compilation_model doc}@anchor{20}@anchor{gnat_ugn/the_gnat_compilation_model id1}@anchor{21}@anchor{gnat_ugn/the_gnat_compilation_model the-gnat-compilation-model}@anchor{9}
-@chapter The GNAT Compilation Model
-
-
-@geindex GNAT compilation model
-
-@geindex Compilation model
-
-This chapter describes the compilation model used by GNAT. Although
-similar to that used by other languages such as C and C++, this model
-is substantially different from the traditional Ada compilation models,
-which are based on a centralized program library. The chapter covers
-the following material:
-
-
-@itemize *
-
-@item 
-Topics related to source file makeup and naming
-
-
-@itemize *
-
-@item 
-@ref{22,,Source Representation}
-
-@item 
-@ref{23,,Foreign Language Representation}
-
-@item 
-@ref{24,,File Naming Topics and Utilities}
-@end itemize
-
-@item 
-@ref{25,,Configuration Pragmas}
-
-@item 
-@ref{26,,Generating Object Files}
-
-@item 
-@ref{27,,Source Dependencies}
-
-@item 
-@ref{28,,The Ada Library Information Files}
-
-@item 
-@ref{29,,Binding an Ada Program}
-
-@item 
-@ref{2a,,GNAT and Libraries}
-
-@item 
-@ref{2b,,Conditional Compilation}
-
-@item 
-@ref{2c,,Mixed Language Programming}
-
-@item 
-@ref{2d,,GNAT and Other Compilation Models}
-
-@item 
-@ref{2e,,Using GNAT Files with External Tools}
-@end itemize
-
-@menu
-* Source Representation:: 
-* Foreign Language Representation:: 
-* File Naming Topics and Utilities:: 
-* Configuration Pragmas:: 
-* Generating Object Files:: 
-* Source Dependencies:: 
-* The Ada Library Information Files:: 
-* Binding an Ada Program:: 
-* GNAT and Libraries:: 
-* Conditional Compilation:: 
-* Mixed Language Programming:: 
-* GNAT and Other Compilation Models:: 
-* Using GNAT Files with External Tools:: 
-
-@end menu
-
-@node Source Representation,Foreign Language Representation,,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id2}@anchor{2f}@anchor{gnat_ugn/the_gnat_compilation_model source-representation}@anchor{22}
-@section Source Representation
-
-
-@geindex Latin-1
-
-@geindex VT
-@geindex HT
-@geindex CR
-@geindex LF
-@geindex FF
-
-Ada source programs are represented in standard text files, using
-Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar
-7-bit ASCII set, plus additional characters used for
-representing foreign languages (see @ref{23,,Foreign Language Representation}
-for support of non-USA character sets). The format effector characters
-are represented using their standard ASCII encodings, as follows:
-
-@quotation
-
-
-@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} 
-@item
-
-Character
-
-@tab
-
-Effect
-
-@tab
-
-Code
-
-@item
-
-@code{VT}
-
-@tab
-
-Vertical tab
-
-@tab
-
-@code{16#0B#}
-
-@item
-
-@code{HT}
-
-@tab
-
-Horizontal tab
-
-@tab
-
-@code{16#09#}
-
-@item
-
-@code{CR}
-
-@tab
-
-Carriage return
-
-@tab
-
-@code{16#0D#}
-
-@item
-
-@code{LF}
-
-@tab
-
-Line feed
-
-@tab
-
-@code{16#0A#}
-
-@item
-
-@code{FF}
-
-@tab
-
-Form feed
-
-@tab
-
-@code{16#0C#}
-
-@end multitable
-
-@end quotation
-
-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:
-@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 @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.
-
-@geindex spec (definition)
-@geindex compilation (definition)
-
-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
-compilation units) is represented using a sequence of files. Similarly,
-you will place each subunit or child unit in a separate file.
-
-@node Foreign Language Representation,File Naming Topics and Utilities,Source Representation,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model foreign-language-representation}@anchor{23}@anchor{gnat_ugn/the_gnat_compilation_model id3}@anchor{30}
-@section Foreign Language Representation
-
-
-GNAT supports the standard character sets defined in Ada as well as
-several other non-standard character sets for use in localized versions
-of the compiler (@ref{31,,Character Set Control}).
-
-@menu
-* Latin-1:: 
-* Other 8-Bit Codes:: 
-* Wide_Character Encodings:: 
-* Wide_Wide_Character Encodings:: 
-
-@end menu
-
-@node Latin-1,Other 8-Bit Codes,,Foreign Language Representation
-@anchor{gnat_ugn/the_gnat_compilation_model id4}@anchor{32}@anchor{gnat_ugn/the_gnat_compilation_model latin-1}@anchor{33}
-@subsection Latin-1
-
-
-@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 @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 @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
-letters can be used in identifiers.
-
-@node Other 8-Bit Codes,Wide_Character Encodings,Latin-1,Foreign Language Representation
-@anchor{gnat_ugn/the_gnat_compilation_model id5}@anchor{34}@anchor{gnat_ugn/the_gnat_compilation_model other-8-bit-codes}@anchor{35}
-@subsection Other 8-Bit Codes
-
-
-GNAT also supports several other 8-bit coding schemes:
-
-@geindex Latin-2
-
-@geindex ISO 8859-2
-
-
-@table @asis
-
-@item `ISO 8859-2 (Latin-2)'
-
-Latin-2 letters allowed in identifiers, with uppercase and lowercase
-equivalence.
-@end table
-
-@geindex Latin-3
-
-@geindex ISO 8859-3
-
-
-@table @asis
-
-@item `ISO 8859-3 (Latin-3)'
-
-Latin-3 letters allowed in identifiers, with uppercase and lowercase
-equivalence.
-@end table
-
-@geindex Latin-4
-
-@geindex ISO 8859-4
-
-
-@table @asis
-
-@item `ISO 8859-4 (Latin-4)'
-
-Latin-4 letters allowed in identifiers, with uppercase and lowercase
-equivalence.
-@end table
-
-@geindex ISO 8859-5
-
-@geindex Cyrillic
-
-
-@table @asis
-
-@item `ISO 8859-5 (Cyrillic)'
-
-ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and
-lowercase equivalence.
-@end table
-
-@geindex ISO 8859-15
-
-@geindex Latin-9
-
-
-@table @asis
-
-@item `ISO 8859-15 (Latin-9)'
-
-ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and
-lowercase equivalence
-@end table
-
-@geindex code page 437 (IBM PC)
-
-
-@table @asis
-
-@item `IBM PC (code page 437)'
-
-This code page is the normal default for PCs in the U.S. It corresponds
-to the original IBM PC character set. This set has some, but not all, of
-the extended Latin-1 letters, but these letters do not have the same
-encoding as Latin-1. In this mode, these letters are allowed in
-identifiers with uppercase and lowercase equivalence.
-@end table
-
-@geindex code page 850 (IBM PC)
-
-
-@table @asis
-
-@item `IBM PC (code page 850)'
-
-This code page is a modification of 437 extended to include all the
-Latin-1 letters, but still not with the usual Latin-1 encoding. In this
-mode, all these letters are allowed in identifiers with uppercase and
-lowercase equivalence.
-
-@item `Full Upper 8-bit'
-
-Any character in the range 80-FF allowed in identifiers, and all are
-considered distinct. In other words, there are no uppercase and lowercase
-equivalences in this range. This is useful in conjunction with
-certain encoding schemes used for some foreign character sets (e.g.,
-the typical method of representing Chinese characters on the PC).
-
-@item `No Upper-Half'
-
-No upper-half characters in the range 80-FF are allowed in identifiers.
-This gives Ada 83 compatibility for identifier names.
-@end table
-
-For precise data on the encodings permitted, and the uppercase and lowercase
-equivalences that are recognized, see the file @code{csets.adb} in
-the GNAT compiler sources. You will need to obtain a full source release
-of GNAT to obtain this file.
-
-@node Wide_Character Encodings,Wide_Wide_Character Encodings,Other 8-Bit Codes,Foreign Language Representation
-@anchor{gnat_ugn/the_gnat_compilation_model id6}@anchor{36}@anchor{gnat_ugn/the_gnat_compilation_model wide-character-encodings}@anchor{37}
-@subsection Wide_Character Encodings
-
-
-GNAT allows wide character codes to appear in character and string
-literals, and also optionally in identifiers, by means of the following
-possible encoding schemes:
-
-
-@table @asis
-
-@item `Hex Coding'
-
-In this encoding, a wide character is represented by the following five
-character sequence:
-
-@example
-ESC a b c d
-@end example
-
-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
-@code{16#A345#}.
-This scheme is compatible with use of the full Wide_Character set.
-
-@item `Upper-Half Coding'
-
-@geindex Upper-Half Coding
-
-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,
-@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.
-
-@item `Shift JIS Coding'
-
-@geindex Shift JIS Coding
-
-A wide character is represented by a two-character sequence,
-@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
-used with this encoding method.
-
-@item `EUC Coding'
-
-@geindex EUC Coding
-
-A wide character is represented by a two-character sequence
-@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.
-
-@item `UTF-8 Coding'
-
-A wide character is represented using
-UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
-10646-1/Am.2. Depending on the character value, the representation
-is a one, two, or three byte sequence:
-
-@example
-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 @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
-(The full UTF-8 scheme allows for encoding 31-bit characters as
-6-byte sequences, and in the following section on wide wide
-characters, the use of these sequences is documented).
-
-@item `Brackets Coding'
-
-In this encoding, a wide character is represented by the following eight
-character sequence:
-
-@example
-[ " a b c d " ]
-@end example
-
-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
-@code{16#A345#}. It is also possible (though not required) to use the
-Brackets coding for upper half characters. For example, the code
-@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
-ACATS (Ada Conformity Assessment Test Suite) test suite distributions.
-@end table
-
-@cartouche
-@quotation Note 
-Some of these coding schemes do not permit the full use of the
-Ada character set. For example, neither Shift JIS nor EUC allow the
-use of the upper half of the Latin-1 set.
-@end quotation
-@end cartouche
-
-@node Wide_Wide_Character Encodings,,Wide_Character Encodings,Foreign Language Representation
-@anchor{gnat_ugn/the_gnat_compilation_model id7}@anchor{38}@anchor{gnat_ugn/the_gnat_compilation_model wide-wide-character-encodings}@anchor{39}
-@subsection Wide_Wide_Character Encodings
-
-
-GNAT allows wide wide character codes to appear in character and string
-literals, and also optionally in identifiers, by means of the following
-possible encoding schemes:
-
-
-@table @asis
-
-@item `UTF-8 Coding'
-
-A wide character is represented using
-UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
-10646-1/Am.2. Depending on the character value, the representation
-of character codes with values greater than 16#FFFF# is a
-is a four, five, or six byte sequence:
-
-@example
-16#01_0000#-16#10_FFFF#:     11110xxx 10xxxxxx 10xxxxxx
-                             10xxxxxx
-16#0020_0000#-16#03FF_FFFF#: 111110xx 10xxxxxx 10xxxxxx
-                             10xxxxxx 10xxxxxx
-16#0400_0000#-16#7FFF_FFFF#: 1111110x 10xxxxxx 10xxxxxx
-                             10xxxxxx 10xxxxxx 10xxxxxx
-@end example
-
-where the @code{xxx} bits correspond to the left-padded bits of the
-32-bit character value.
-
-@item `Brackets Coding'
-
-In this encoding, a wide wide character is represented by the following ten or
-twelve byte character sequence:
-
-@example
-[ " a b c d e f " ]
-[ " a b c d e f g h " ]
-@end example
-
-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
-@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
-ACATS (Ada Conformity Assessment Test Suite) test suite distributions.
-@end table
-
-@node File Naming Topics and Utilities,Configuration Pragmas,Foreign Language Representation,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model file-naming-topics-and-utilities}@anchor{24}@anchor{gnat_ugn/the_gnat_compilation_model id8}@anchor{3a}
-@section File Naming Topics and Utilities
-
-
-GNAT has a default file naming scheme and also provides the user with
-a high degree of control over how the names and extensions of the
-source files correspond to the Ada compilation units that they contain.
-
-@menu
-* File Naming Rules:: 
-* Using Other File Names:: 
-* Alternative File Naming Schemes:: 
-* Handling Arbitrary File Naming Conventions with gnatname:: 
-* File Name Krunching with gnatkr:: 
-* Renaming Files with gnatchop:: 
-
-@end menu
-
-@node File Naming Rules,Using Other File Names,,File Naming Topics and Utilities
-@anchor{gnat_ugn/the_gnat_compilation_model file-naming-rules}@anchor{3b}@anchor{gnat_ugn/the_gnat_compilation_model id9}@anchor{3c}
-@subsection File Naming Rules
-
-
-The default file name is determined by the name of the unit that the
-file contains. The name is formed by taking the full expanded name of
-the unit and replacing the separating dots with hyphens and using
-lowercase for all letters.
-
-An exception arises if the file name generated by the above rules starts
-with one of the characters
-@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
-@code{s-}, @code{a-}, @code{i-}, and @code{g-},
-respectively.
-
-The file extension is @code{.ads} for a spec and
-@code{.adb} for a body. The following table shows some
-examples of these rules.
-
-@quotation
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@item
-
-Source File
-
-@tab
-
-Ada Compilation Unit
-
-@item
-
-@code{main.ads}
-
-@tab
-
-Main (spec)
-
-@item
-
-@code{main.adb}
-
-@tab
-
-Main (body)
-
-@item
-
-@code{arith_functions.ads}
-
-@tab
-
-Arith_Functions (package spec)
-
-@item
-
-@code{arith_functions.adb}
-
-@tab
-
-Arith_Functions (package body)
-
-@item
-
-@code{func-spec.ads}
-
-@tab
-
-Func.Spec (child package spec)
-
-@item
-
-@code{func-spec.adb}
-
-@tab
-
-Func.Spec (child package body)
-
-@item
-
-@code{main-sub.adb}
-
-@tab
-
-Sub (subunit of Main)
-
-@item
-
-@code{a~bad.adb}
-
-@tab
-
-A.Bad (child package body)
-
-@end multitable
-
-@end quotation
-
-Following these rules can result in excessively long
-file names if corresponding
-unit names are long (for example, if child units or subunits are
-heavily nested). An option is available to shorten such long file names
-(called file name ‘krunching’). This may be particularly useful when
-programs being developed with GNAT are to be used on operating systems
-with limited file name lengths. @ref{3d,,Using gnatkr}.
-
-Of course, no file shortening algorithm can guarantee uniqueness over
-all possible unit names; if file name krunching is used, it is your
-responsibility to ensure no name clashes occur. Alternatively you
-can specify the exact file names that you want used, as described
-in the next section. Finally, if your Ada programs are migrating from a
-compiler with a different naming convention, you can use the gnatchop
-utility to produce source files that follow the GNAT naming conventions.
-(For details see @ref{1d,,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
-@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.
-
-@node Using Other File Names,Alternative File Naming Schemes,File Naming Rules,File Naming Topics and Utilities
-@anchor{gnat_ugn/the_gnat_compilation_model id10}@anchor{3e}@anchor{gnat_ugn/the_gnat_compilation_model using-other-file-names}@anchor{1c}
-@subsection Using Other File Names
-
-
-@geindex File names
-
-In the previous section, we have described the default rules used by
-GNAT to determine the file name in which a given unit resides. It is
-often convenient to follow these default rules, and if you follow them,
-the compiler knows without being explicitly told where to find all
-the files it needs.
-
-@geindex Source_File_Name pragma
-
-However, in some cases, particularly when a program is imported from
-another Ada compiler environment, it may be more convenient for the
-programmer to specify which file names contain which units. GNAT allows
-arbitrary file names to be used by means of the Source_File_Name pragma.
-The form of this pragma is as shown in the following examples:
-
-@example
-pragma Source_File_Name (My_Utilities.Stacks,
-  Spec_File_Name => "myutilst_a.ada");
-pragma Source_File_name (My_Utilities.Stacks,
-  Body_File_Name => "myutilst.ada");
-@end example
-
-As shown in this example, the first argument for the pragma is the unit
-name (in this example a child unit). The second argument has the form
-of a named association. The identifier
-indicates whether the file name is for a spec or a body;
-the file name itself is given by a string literal.
-
-The source file name pragma is a configuration pragma, which means that
-normally it will be placed in the @code{gnat.adc}
-file used to hold configuration
-pragmas that apply to a complete compilation environment.
-For more details on how the @code{gnat.adc} file is created and used
-see @ref{3f,,Handling of Configuration Pragmas}.
-
-@geindex gnat.adc
-
-GNAT allows completely arbitrary file names to be specified using the
-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 @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
-
-@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 @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
-@anchor{gnat_ugn/the_gnat_compilation_model alternative-file-naming-schemes}@anchor{40}@anchor{gnat_ugn/the_gnat_compilation_model id11}@anchor{41}
-@subsection Alternative File Naming Schemes
-
-
-@geindex File naming schemes
-@geindex alternative
-
-@geindex File names
-
-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
-a maintenance problem.
-
-@geindex Source_File_Name pragma
-
-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
-@code{Source_File_Name} pragmas having the following format:
-
-@example
-pragma Source_File_Name (
-   Spec_File_Name  => FILE_NAME_PATTERN
- [ , Casing          => CASING_SPEC]
- [ , Dot_Replacement => STRING_LITERAL ] );
-
-pragma Source_File_Name (
-   Body_File_Name  => FILE_NAME_PATTERN
- [ , Casing          => CASING_SPEC ]
- [ , Dot_Replacement => STRING_LITERAL ] ) ;
-
-pragma Source_File_Name (
-   Subunit_File_Name  => FILE_NAME_PATTERN
- [ , Casing          => CASING_SPEC ]
- [ , Dot_Replacement => STRING_LITERAL ] ) ;
-
-FILE_NAME_PATTERN ::= STRING_LITERAL
-CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
-@end example
-
-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
-@code{Casing} indicates
-whether the unit name is to be all upper-case letters, all lower-case letters,
-or mixed-case. If no
-@code{Casing} parameter is used, then the default is all
-lower-case.
-
-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
-@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 @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
-contains a subunit and a child unit with the same unit name. Although
-both units cannot appear in the same partition, the Ada Reference Manual
-allows (but does not require) the possibility of the two units coexisting
-in the same environment.
-
-The file name translation works in the following steps:
-
-
-@itemize *
-
-@item 
-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 @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 @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
-
-As an example of the use of this mechanism, consider a commonly used scheme
-in which file names are all lower case, with separating periods copied
-unchanged to the resulting file name, and specs end with @code{.1.ada}, and
-bodies end with @code{.2.ada}. GNAT will follow this scheme if the following
-two pragmas appear:
-
-@example
-pragma Source_File_Name
-  (Spec_File_Name => ".1.ada");
-pragma Source_File_Name
-  (Body_File_Name => ".2.ada");
-@end example
-
-The default GNAT scheme is actually implemented by providing the following
-default pragmas internally:
-
-@example
-pragma Source_File_Name
-  (Spec_File_Name => ".ads", Dot_Replacement => "-");
-pragma Source_File_Name
-  (Body_File_Name => ".adb", Dot_Replacement => "-");
-@end example
-
-Our final example implements a scheme typically used with one of the
-Ada 83 compilers, where the separator character for subunits was ‘__’
-(two underscores), specs were identified by adding @code{_.ADA}, bodies
-by adding @code{.ADA}, and subunits by
-adding @code{.SEP}. All file names were
-upper case. Child units were not present of course since this was an
-Ada 83 compiler, but it seems reasonable to extend this scheme to use
-the same double underscore separator for child units.
-
-@example
-pragma Source_File_Name
-  (Spec_File_Name => "_.ADA",
-   Dot_Replacement => "__",
-   Casing = Uppercase);
-pragma Source_File_Name
-  (Body_File_Name => ".ADA",
-   Dot_Replacement => "__",
-   Casing = Uppercase);
-pragma Source_File_Name
-  (Subunit_File_Name => ".SEP",
-   Dot_Replacement => "__",
-   Casing = Uppercase);
-@end example
-
-@geindex gnatname
-
-@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{42}@anchor{gnat_ugn/the_gnat_compilation_model id12}@anchor{43}
-@subsection Handling Arbitrary File Naming Conventions with @code{gnatname}
-
-
-@geindex File Naming Conventions
-
-@menu
-* Arbitrary File Naming Conventions:: 
-* Running gnatname:: 
-* Switches for gnatname:: 
-* Examples of gnatname Usage:: 
-
-@end menu
-
-@node Arbitrary File Naming Conventions,Running gnatname,,Handling Arbitrary File Naming Conventions with gnatname
-@anchor{gnat_ugn/the_gnat_compilation_model arbitrary-file-naming-conventions}@anchor{44}@anchor{gnat_ugn/the_gnat_compilation_model id13}@anchor{45}
-@subsubsection Arbitrary 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
-(@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
-conventions, the GNAT compiler must be given additional information through
-a configuration pragmas file (@ref{25,,Configuration Pragmas})
-or a project file.
-When the non-standard file naming conventions are well-defined,
-a small number of pragmas @code{Source_File_Name} specifying a naming pattern
-(@ref{40,,Alternative File Naming Schemes}) may be sufficient. However,
-if the file naming conventions are irregular or arbitrary, a number
-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 @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 id14}@anchor{46}@anchor{gnat_ugn/the_gnat_compilation_model running-gnatname}@anchor{47}
-@subsubsection Running @code{gnatname}
-
-
-The usual form of the @code{gnatname} command is:
-
-@example
-$ 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,
-@code{gnatname} will display its usage.
-
-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,
-@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 @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.
-
-@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 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.
-
-Examples of Naming Patterns are:
-
-@example
-"*.[12].ada"
-"*.ad[sb]*"
-"body_*"    "spec_*"
-@end example
-
-For a more complete description of the syntax of Naming Patterns,
-see the second kind of regular expressions described in @code{g-regexp.ads}
-(the ‘Glob’ regular expressions).
-
-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 @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{48}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatname}@anchor{49}
-@subsubsection Switches for @code{gnatname}
-
-
-Switches for @code{gnatname} must precede any specified Naming Pattern.
-
-You may specify any of the following switches to @code{gnatname}:
-
-@geindex --version (gnatname)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display Copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatname)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-
-@item @code{--subdirs=`dir'}
-
-Real object, library or exec directories are subdirectories <dir> of the
-specified ones.
-
-@item @code{--no-backup}
-
-Do not create a backup copy of an existing project file.
-
-@item @code{--and}
-
-Start another section of directories/patterns.
-@end table
-
-@geindex -c (gnatname)
-
-
-@table @asis
-
-@item @code{-c`filename'}
-
-Create a configuration pragmas file @code{filename} (instead of the default
-@code{gnat.adc}).
-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 @code{-c}.
-When a switch @code{-c} is
-specified, no switch @code{-P} may be specified (see below).
-@end table
-
-@geindex -d (gnatname)
-
-
-@table @asis
-
-@item @code{-d`dir'}
-
-Look for source files in directory @code{dir}. There may be zero, one or more
-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 @code{-d}
-is specified, the current working directory will not be searched for source
-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
-@code{-c},
-or to the directory of the project file specified with switch
-@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 @code{-d} must exist and be readable.
-@end table
-
-@geindex -D (gnatname)
-
-
-@table @asis
-
-@item @code{-D`filename'}
-
-Look for source files in all directories listed in text file @code{filename}.
-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 @code{-D} is equivalent to specifying as many
-switches @code{-d} as there are nonempty lines in
-@code{file}.
-
-@item @code{-eL}
-
-Follow symbolic links when processing project files.
-
-@geindex -f (gnatname)
-
-@item @code{-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.
-For example,
-
-@example
-gnatname -Pprj -f"*.c" "*.ada"
-@end example
-
-will look for Ada units in all files with the @code{.ada} extension,
-and will add to the list of file for project @code{prj.gpr} the C files
-with extension @code{.c}.
-
-@geindex -h (gnatname)
-
-@item @code{-h}
-
-Output usage (help) information. The output is written to @code{stdout}.
-
-@geindex -P (gnatname)
-
-@item @code{-P`proj'}
-
-Create or update project file @code{proj}. There may be zero, one or more space
-between @code{-P} and @code{proj}. @code{proj} may include directory
-information. @code{proj} must be writable.
-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.
-
-@geindex -v (gnatname)
-
-@item @code{-v}
-
-Verbose mode. Output detailed explanation of behavior to @code{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
-the Naming Patterns, an indication of whether the file contains a unit,
-and if so the name of the unit.
-@end table
-
-@geindex -v -v (gnatname)
-
-
-@table @asis
-
-@item @code{-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.
-
-@geindex -x (gnatname)
-
-@item @code{-x`pattern'}
-
-Excluded patterns. Using this switch, it is possible to exclude some files
-that would match the name patterns. For example,
-
-@example
-gnatname -x "*_nt.ada" "*.ada"
-@end example
-
-will look for Ada units in all files with the @code{.ada} extension,
-except those whose names end with @code{_nt.ada}.
-@end table
-
-@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{4a}@anchor{gnat_ugn/the_gnat_compilation_model id16}@anchor{4b}
-@subsubsection Examples of @code{gnatname} Usage
-
-
-@example
-$ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*"
-@end 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
-@code{-d sources}) must exist and be readable.
-
-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 @code{-d} may be used,
-even in conjunction with one or several switches
-@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{4c}@anchor{gnat_ugn/the_gnat_compilation_model id17}@anchor{4d}
-@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
-@code{gnatkr} utility that can be used to determine the result of
-applying this shortening.
-
-@menu
-* About gnatkr:: 
-* Using gnatkr:: 
-* Krunching Method:: 
-* Examples of gnatkr Usage:: 
-
-@end menu
-
-@node About gnatkr,Using gnatkr,,File Name Krunching with gnatkr
-@anchor{gnat_ugn/the_gnat_compilation_model about-gnatkr}@anchor{4e}@anchor{gnat_ugn/the_gnat_compilation_model id18}@anchor{4f}
-@subsubsection About @code{gnatkr}
-
-
-The default file naming rule in GNAT
-is that the file name must be derived from
-the unit name. The exact default rule is as follows:
-
-
-@itemize *
-
-@item 
-Take the unit name and replace all dots by hyphens.
-
-@item 
-If such a replacement occurs in the
-second character position of a name, and the first character is
-@code{a}, @code{g}, @code{s}, or @code{i},
-then replace the dot by the character
-@code{~} (tilde)
-instead of a minus.
-
-The reason for this exception is to avoid clashes
-with the standard names for children of System, Ada, Interfaces,
-and GNAT, which use the prefixes
-@code{s-}, @code{a-}, @code{i-}, and @code{g-},
-respectively.
-@end itemize
-
-The @code{-gnatk`nn'}
-switch of the compiler activates a ‘krunching’
-circuit that limits file names to nn characters (where nn is a decimal
-integer).
-
-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{50}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatkr}@anchor{3d}
-@subsubsection Using @code{gnatkr}
-
-
-The @code{gnatkr} command has the form:
-
-@example
-$ gnatkr name [ length ]
-@end example
-
-@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
-characters other than period). If an extension is present then it will
-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 @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 @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.
-
-@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.
-
-The output is the krunched name. The output has an extension only if the
-original argument was a file name with an extension.
-
-@node Krunching Method,Examples of gnatkr Usage,Using gnatkr,File Name Krunching with gnatkr
-@anchor{gnat_ugn/the_gnat_compilation_model id20}@anchor{51}@anchor{gnat_ugn/the_gnat_compilation_model krunching-method}@anchor{52}
-@subsubsection Krunching Method
-
-
-The initial file name is determined by the name of the unit that the file
-contains. The name is formed by taking the full expanded name of the
-unit and replacing the separating dots with hyphens and
-using lowercase
-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 @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:
-
-
-@itemize *
-
-@item 
-The name is divided into segments separated by hyphens, tildes or
-underscores and all hyphens, tildes, and underscores are
-eliminated. If this leaves the name short enough, we are done.
-
-@item 
-If the name is too long, the longest segment is located (left-most
-if there are two of equal length), and shortened by dropping
-its last character. This is repeated until the name is short enough.
-
-As an example, consider the krunching of @code{our-strings-wide_fixed.adb}
-to fit the name into 8 characters as required by some operating systems:
-
-@example
-our-strings-wide_fixed 22
-our strings wide fixed 19
-our string  wide fixed 18
-our strin   wide fixed 17
-our stri    wide fixed 16
-our stri    wide fixe  15
-our str     wide fixe  14
-our str     wid  fixe  13
-our str     wid  fix   12
-ou  str     wid  fix   11
-ou  st      wid  fix   10
-ou  st      wi   fix   9
-ou  st      wi   fi    8
-Final file name: oustwifi.adb
-@end example
-
-@item 
-The file names for all predefined units are always krunched to eight
-characters. The krunching of these predefined units uses the following
-special prefix replacements:
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
-@item
-
-Prefix
-
-@tab
-
-Replacement
-
-@item
-
-@code{ada-}
-
-@tab
-
-@code{a-}
-
-@item
-
-@code{gnat-}
-
-@tab
-
-@code{g-}
-
-@item
-
-@code{interfac es-}
-
-@tab
-
-@code{i-}
-
-@item
-
-@code{system-}
-
-@tab
-
-@code{s-}
-
-@end multitable
-
-
-These system files have a hyphen in the second character position. That
-is why normal user files replace such a character with a
-tilde, to avoid confusion with system file names.
-
-As an example of this special rule, consider
-@code{ada-strings-wide_fixed.adb}, which gets krunched as follows:
-
-@example
-ada-strings-wide_fixed 22
-a-  strings wide fixed 18
-a-  string  wide fixed 17
-a-  strin   wide fixed 16
-a-  stri    wide fixed 15
-a-  stri    wide fixe  14
-a-  str     wide fixe  13
-a-  str     wid  fixe  12
-a-  str     wid  fix   11
-a-  st      wid  fix   10
-a-  st      wi   fix   9
-a-  st      wi   fi    8
-Final file name: a-stwifi.adb
-@end example
-@end itemize
-
-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 @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 examples-of-gnatkr-usage}@anchor{53}@anchor{gnat_ugn/the_gnat_compilation_model id21}@anchor{54}
-@subsubsection Examples of @code{gnatkr} Usage
-
-
-@example
-$ gnatkr very_long_unit_name.ads      --> velounna.ads
-$ gnatkr grandparent-parent-child.ads --> grparchi.ads
-$ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads
-$ gnatkr grandparent-parent-child     --> grparchi
-$ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads
-$ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads
-@end 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{55}@anchor{gnat_ugn/the_gnat_compilation_model renaming-files-with-gnatchop}@anchor{1d}
-@subsection Renaming Files with @code{gnatchop}
-
-
-@geindex gnatchop
-
-This section discusses how to handle files with multiple units by using
-the @code{gnatchop} utility. This utility is also useful in renaming
-files to meet the standard GNAT default file naming conventions.
-
-@menu
-* Handling Files with Multiple Units:: 
-* Operating gnatchop in Compilation Mode:: 
-* Command Line for gnatchop:: 
-* Switches for gnatchop:: 
-* Examples of gnatchop Usage:: 
-
-@end menu
-
-@node Handling Files with Multiple Units,Operating gnatchop in Compilation Mode,,Renaming Files with gnatchop
-@anchor{gnat_ugn/the_gnat_compilation_model handling-files-with-multiple-units}@anchor{56}@anchor{gnat_ugn/the_gnat_compilation_model id23}@anchor{57}
-@subsubsection Handling Files with Multiple Units
-
-
-The basic compilation model of GNAT requires that a file submitted to the
-compiler have only one unit and there be a strict correspondence
-between the file name and the unit name.
-
-If you want to keep your files with multiple units,
-perhaps to maintain compatibility with some other Ada compilation system,
-you can use @code{gnatname} to generate or update your project files.
-Generated or modified project files can be processed by GNAT.
-
-See @ref{42,,Handling Arbitrary File Naming Conventions with gnatname}
-for more details on how to use @cite{gnatname}.
-
-Alternatively, 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 @code{gnatchop} once, generate the
-new set of files and work with them from that point on.
-
-Note that if your file containing multiple units starts with a byte order
-mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop
-will each start with a copy of this BOM, meaning that they can be compiled
-automatically in UTF-8 mode without needing to specify an explicit encoding.
-
-@node Operating gnatchop in Compilation Mode,Command Line for gnatchop,Handling Files with Multiple Units,Renaming Files with gnatchop
-@anchor{gnat_ugn/the_gnat_compilation_model id24}@anchor{58}@anchor{gnat_ugn/the_gnat_compilation_model operating-gnatchop-in-compilation-mode}@anchor{59}
-@subsubsection Operating gnatchop in Compilation Mode
-
-
-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
-that configuration pragmas always belong to the following unit. Any comments
-belong to the following unit. These rules
-almost always result in the right choice of
-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 @code{gnatchop}.
-
-However, using a special option to activate ‘compilation mode’,
-@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 @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
-on submitting such a file to the compiler, namely that these pragmas
-should apply to all subsequent compilations in the same compilation
-environment. Using GNAT, the current directory, possibly containing a
-@code{gnat.adc} file is the representation
-of a compilation environment. For more information on the
-@code{gnat.adc} file, see @ref{3f,,Handling of Configuration Pragmas}.
-
-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
-behavior provides the required behavior described in the RM for the
-actions to be taken on compiling such a file, namely that the pragmas
-apply to all units in the compilation, but not to subsequently compiled
-units.
-
-Finally, if configuration pragmas appear between units, they are appended
-to the previous unit. This results in the previous unit being illegal,
-since the compiler does not accept configuration pragmas that follow
-a unit. This provides the required RM behavior that forbids configuration
-pragmas other than those preceding the first compilation unit of a
-compilation.
-
-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 @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 command-line-for-gnatchop}@anchor{5a}@anchor{gnat_ugn/the_gnat_compilation_model id25}@anchor{5b}
-@subsubsection Command Line for @code{gnatchop}
-
-
-The @code{gnatchop} command has the form:
-
-@example
-$ gnatchop switches file_name [file_name ...]
-      [directory]
-@end example
-
-The only required argument is the file name of the file to be chopped.
-There are no restrictions on the form of this file name. The file itself
-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, @code{gnatchop} generates one output file in
-the current directory for each unit in each of the files.
-
-@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.
-
-For example, given a
-file called @code{hellofiles} containing
-
-@example
-procedure Hello;
-
-with Ada.Text_IO; use Ada.Text_IO;
-procedure Hello is
-begin
-   Put_Line ("Hello");
-end Hello;
-@end example
-
-the command
-
-@example
-$ gnatchop hellofiles
-@end example
-
-generates two files in the current directory, one called
-@code{hello.ads} containing the single line that is the procedure spec,
-and the other called @code{hello.adb} containing the remaining text. The
-original file is not affected. The generated files can be compiled in
-the normal manner.
-
-When gnatchop is invoked on a file that is empty or that contains only empty
-lines and/or comments, gnatchop will not fail, but will not produce any
-new sources.
-
-For example, given a
-file called @code{toto.txt} containing
-
-@example
---  Just a comment
-@end example
-
-the command
-
-@example
-$ gnatchop toto.txt
-@end example
-
-will not produce any new file and will result in the following warnings:
-
-@example
-toto.txt:1:01: warning: empty file, contains no compilation units
-no compilation units found
-no source files written
-@end example
-
-@node Switches for gnatchop,Examples of gnatchop Usage,Command Line for gnatchop,Renaming Files with gnatchop
-@anchor{gnat_ugn/the_gnat_compilation_model id26}@anchor{5c}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatchop}@anchor{5d}
-@subsubsection Switches for @code{gnatchop}
-
-
-@code{gnatchop} recognizes the following switches:
-
-@geindex --version (gnatchop)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display Copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatchop)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
-
-@geindex -c (gnatchop)
-
-
-@table @asis
-
-@item @code{-c}
-
-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`xxx'}
-
-This passes the given @code{-gnat`xxx'} switch to @code{gnat} which is
-used to parse the given file. Not all `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 @code{gnatchop} to generate a brief help summary to the standard
-output file showing usage information.
-@end table
-
-@geindex -k (gnatchop)
-
-
-@table @asis
-
-@item @code{-k`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 @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 @code{-k} switch
-is present then
-there is no limit on the length of file names.
-@end table
-
-@geindex -p (gnatchop)
-
-
-@table @asis
-
-@item @code{-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
-@code{gnatchop} is used as part of a standard build process.
-@end table
-
-@geindex -q (gnatchop)
-
-
-@table @asis
-
-@item @code{-q}
-
-Causes output of informational messages indicating the set of generated
-files to be suppressed. Warnings and error messages are unaffected.
-@end table
-
-@geindex -r (gnatchop)
-
-@geindex Source_Reference pragmas
-
-
-@table @asis
-
-@item @code{-r}
-
-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
-@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 @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 @code{Source_Reference}
-pragma referencing a third file, then gnatchop respects
-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 @code{gnatchop}
-is used in conjunction with @code{gnatprep} to compile files that
-contain preprocessing statements and multiple units.
-@end table
-
-@geindex -v (gnatchop)
-
-
-@table @asis
-
-@item @code{-v}
-
-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
-
-@geindex -w (gnatchop)
-
-
-@table @asis
-
-@item @code{-w}
-
-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
-check, and causes all but the last instance of such duplicated
-units to be skipped.
-@end table
-
-@geindex --GCC= (gnatchop)
-
-
-@table @asis
-
-@item @code{--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.
-@end table
-
-@node Examples of gnatchop Usage,,Switches for gnatchop,Renaming Files with gnatchop
-@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatchop-usage}@anchor{5e}@anchor{gnat_ugn/the_gnat_compilation_model id27}@anchor{5f}
-@subsubsection Examples of @code{gnatchop} Usage
-
-
-@example
-$ gnatchop -w hello_s.ada prerelease/files
-@end example
-
-Chops the source file @code{hello_s.ada}. The output files will be
-placed in the directory @code{prerelease/files},
-overwriting any
-files with matching names in that directory (no files in the current
-directory are modified).
-
-@example
-$ gnatchop archive
-@end example
-
-Chops the source file @code{archive}
-into the current directory. One
-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 @code{cat}
-command), and then
-@code{gnatchop} is used at the other end to reconstitute the original
-file names.
-
-@example
-$ gnatchop file1 file2 file3 direc
-@end example
-
-Chops all units in files @code{file1}, @code{file2}, @code{file3}, placing
-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
-@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.
-
-@node Configuration Pragmas,Generating Object Files,File Naming Topics and Utilities,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model configuration-pragmas}@anchor{25}@anchor{gnat_ugn/the_gnat_compilation_model id28}@anchor{60}
-@section Configuration Pragmas
-
-
-@geindex Configuration pragmas
-
-@geindex Pragmas
-@geindex configuration
-
-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 @code{Implementation_Defined_Pragmas} chapter in the
-@cite{GNAT_Reference_Manual} for details on these
-additional GNAT-specific configuration pragmas.
-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:
-
-@example
-Ada_83
-Ada_95
-Ada_05
-Ada_2005
-Ada_12
-Ada_2012
-Ada_2022
-Aggregate_Individually_Assign
-Allow_Integer_Address
-Annotate
-Assertion_Policy
-Assume_No_Invalid_Values
-C_Pass_By_Copy
-Check_Float_Overflow
-Check_Name
-Check_Policy
-Component_Alignment
-Convention_Identifier
-Debug_Policy
-Default_Scalar_Storage_Order
-Default_Storage_Pool
-Detect_Blocking
-Disable_Atomic_Synchronization
-Discard_Names
-Elaboration_Checks
-Eliminate
-Enable_Atomic_Synchronization
-Extend_System
-Extensions_Allowed
-External_Name_Casing
-Fast_Math
-Favor_Top_Level
-Ignore_Pragma
-Implicit_Packing
-Initialize_Scalars
-Interrupt_State
-License
-Locking_Policy
-No_Component_Reordering
-No_Heap_Finalization
-No_Strict_Aliasing
-Normalize_Scalars
-Optimize_Alignment
-Overflow_Mode
-Overriding_Renamings
-Partition_Elaboration_Policy
-Persistent_BSS
-Prefix_Exception_Messages
-Priority_Specific_Dispatching
-Profile
-Profile_Warnings
-Queuing_Policy
-Rename_Pragma
-Restrictions
-Restriction_Warnings
-Reviewable
-Short_Circuit_And_Or
-Source_File_Name
-Source_File_Name_Project
-SPARK_Mode
-Style_Checks
-Suppress
-Suppress_Exception_Locations
-Task_Dispatching_Policy
-Unevaluated_Use_Of_Old
-Unsuppress
-Use_VADS_Size
-Validity_Checks
-Warning_As_Error
-Warnings
-Wide_Character_Encoding
-@end example
-
-@menu
-* Handling of Configuration Pragmas:: 
-* The Configuration Pragmas Files:: 
-
-@end menu
-
-@node Handling of Configuration Pragmas,The Configuration Pragmas Files,,Configuration Pragmas
-@anchor{gnat_ugn/the_gnat_compilation_model handling-of-configuration-pragmas}@anchor{3f}@anchor{gnat_ugn/the_gnat_compilation_model id29}@anchor{61}
-@subsection Handling of Configuration Pragmas
-
-
-Configuration pragmas may either appear at the start of a compilation
-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 @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{59,,Operating gnatchop in Compilation Mode} for details.
-However, for most purposes, it will be more convenient to edit the
-@code{gnat.adc} file that contains configuration pragmas directly,
-as described in the following section.
-
-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
-@code{No_Tasking}) are
-recognized wherever they appear
-and can be freely inherited, e.g. from a `with'ed unit to the `with'ing
-unit. This makes sense since the binder will in any case insist on seeing
-consistent use, so any unit not conforming to any restrictions that are
-anywhere in the partition will be rejected, and you might as well find
-that out at compile time rather than at bind time.
-
-For restrictions that do not require partition-wide consistency, e.g.
-SPARK or No_Implementation_Attributes, in general the restriction applies
-only to the unit in which the pragma appears, and not to any other units.
-
-The exception is No_Elaboration_Code which always applies to the entire
-object file from a compilation, i.e. to the body, spec, and all subunits.
-This restriction can be specified in a configuration pragma file, or it
-can be on the body and/or the spec (in either case it applies to all the
-relevant units). It can appear on a subunit only if it has previously
-appeared in the body of spec.
-
-@node The Configuration Pragmas Files,,Handling of Configuration Pragmas,Configuration Pragmas
-@anchor{gnat_ugn/the_gnat_compilation_model id30}@anchor{62}@anchor{gnat_ugn/the_gnat_compilation_model the-configuration-pragmas-files}@anchor{63}
-@subsection The Configuration Pragmas Files
-
-
-@geindex gnat.adc
-
-In GNAT a compilation environment is defined by the current
-directory at the time that a compile command is given. This current
-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 @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
-@code{gnatmake} will recompile the source.
-
-Configuration pragmas may be entered into the @code{gnat.adc} file
-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=`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 @code{-gnatA} is not used).
-
-It is allowable to specify several switches @code{-gnatec=}, all of which
-will be taken into account.
-
-Files containing configuration pragmas specified with switches
-@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 @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
-@code{gprbuild}, @code{gnatmake}, and @code{gnatcheck}.
-
-By default, configuration pragma files are stored by their absolute paths in
-ALI files. You can use the @code{-gnateb} switch in order to store them by
-their basename instead.
-
-If you are using project file, a separate mechanism is provided using
-project attributes.
-
-@c --Comment
-@c See :ref:`Specifying_Configuration_Pragmas` for more details.
-
-@node Generating Object Files,Source Dependencies,Configuration Pragmas,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model generating-object-files}@anchor{26}@anchor{gnat_ugn/the_gnat_compilation_model id31}@anchor{64}
-@section Generating Object Files
-
-
-An Ada program consists of a set of source files, and the first step in
-compiling the program is to generate the corresponding object files.
-These are generated by compiling a subset of these source files.
-The files you need to compile are the following:
-
-
-@itemize *
-
-@item 
-If a package spec has no body, compile the package spec to produce the
-object file for the package.
-
-@item 
-If a package has both a spec and a body, compile the body to produce the
-object file for the package. The source file for the package spec need
-not be compiled in this case because there is only one object file, which
-contains the code for both the spec and body of the package.
-
-@item 
-For a subprogram, compile the subprogram body to produce the object file
-for the subprogram. The spec, if one is present, is as usual in a
-separate file, and need not be compiled.
-@end itemize
-
-@geindex Subunits
-
-
-@itemize *
-
-@item 
-In the case of subunits, only compile the parent unit. A single object
-file is generated for the entire subunit tree, which includes all the
-subunits.
-
-@item 
-Compile child units independently of their parent units
-(though, of course, the spec of all the ancestor unit must be present in order
-to compile a child unit).
-
-@geindex Generics
-
-@item 
-Compile generic units in the same manner as any other units. The object
-files in this case are small dummy files that contain at most the
-flag used for elaboration checking. This is because GNAT always handles generic
-instantiation by means of macro expansion. However, it is still necessary to
-compile generic units, for dependency checking and elaboration purposes.
-@end itemize
-
-The preceding rules describe the set of files that must be compiled to
-generate the object files for a program. Each object file has the same
-name as the corresponding source file, except that the extension is
-@code{.o} as usual.
-
-You may wish to compile other files for the purpose of checking their
-syntactic and semantic correctness. For example, in the case where a
-package has a separate spec and body, you would not normally compile the
-spec. However, it is convenient in practice to compile the spec to make
-sure it is error-free before compiling clients of this spec, because such
-compilations will fail if there is an error in the spec.
-
-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 @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{65}@anchor{gnat_ugn/the_gnat_compilation_model source-dependencies}@anchor{27}
-@section 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
-@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
-additional source files as follows:
-
-
-@itemize *
-
-@item 
-If a file being compiled `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 `with'ed implicitly either because they are parents
-of `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 instantiates a library level generic unit, the
-object file depends on both the spec and body files for this generic
-unit.
-
-@item 
-If a file being compiled instantiates a generic unit defined within a
-package, the object file depends on the body file for the package as
-well as the spec file.
-@end itemize
-
-@geindex Inline
-
-@geindex -gnatn switch
-
-
-@itemize *
-
-@item 
-If a file being compiled contains a call to a subprogram for which
-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 @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 @code{-gnatn},
-the use of this switch generates additional dependencies.
-
-When using a gcc-based back end, then the use of
-@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.
-
-@item 
-If an object file @code{O} depends on the proper body of a subunit through
-inlining or instantiation, it depends on the parent unit of the subunit.
-This means that any modification of the parent unit or one of its subunits
-affects the compilation of @code{O}.
-
-@item 
-The object file for a parent unit depends on all its subunit body files.
-
-@item 
-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 @code{A} `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
-Ada language standard. However, it is a superset of what the
-standard describes, because it includes generic, inline, and subunit
-dependencies.
-
-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 @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 @code{gnatmake}.
-@end itemize
-
-@node The Ada Library Information Files,Binding an Ada Program,Source Dependencies,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id33}@anchor{66}@anchor{gnat_ugn/the_gnat_compilation_model the-ada-library-information-files}@anchor{28}
-@section The Ada Library Information Files
-
-
-@geindex Ada Library Information files
-
-@geindex ALI files
-
-Each compilation actually generates two output files. The first of these
-is the normal object file that has a @code{.o} extension. The second is a
-text file containing full dependency information. It has the same
-name as the source file, but an @code{.ali} extension.
-This file is known as the Ada Library Information (@code{ALI}) file.
-The following information is contained in the @code{ALI} file.
-
-
-@itemize *
-
-@item 
-Version information (indicates which version of GNAT was used to compile
-the unit(s) in question)
-
-@item 
-Main program information (including priority and time slice settings,
-as well as the wide character encoding used during compilation).
-
-@item 
-List of arguments used in the @code{gcc} command for the compilation
-
-@item 
-Attributes of the unit, including configuration pragmas used, an indication
-of whether the compilation was successful, exception model used etc.
-
-@item 
-A list of relevant restrictions applying to the unit (used for consistency)
-checking.
-
-@item 
-Categorization information (e.g., use of pragma @code{Pure}).
-
-@item 
-Information on all `with'ed units, including presence of
-@code{Elaborate} or @code{Elaborate_All} pragmas.
-
-@item 
-Information from any @code{Linker_Options} pragmas used in the unit
-
-@item 
-Information on the use of @code{Body_Version} or @code{Version}
-attributes in the unit.
-
-@item 
-Dependency information. This is a list of files, together with
-time stamp and checksum information. These are files on which
-the unit depends in the sense that recompilation is required
-if any of these units are modified.
-
-@item 
-Cross-reference data. Contains information on all entities referenced
-in the unit. Used by some tools 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 @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
-@anchor{gnat_ugn/the_gnat_compilation_model binding-an-ada-program}@anchor{29}@anchor{gnat_ugn/the_gnat_compilation_model id34}@anchor{67}
-@section Binding an Ada Program
-
-
-When using languages such as C and C++, once the source files have been
-compiled the only remaining step in building an executable program
-is linking the object modules together. This means that it is possible to
-link an inconsistent version of a program, in which two units have
-included different versions of the same header.
-
-The rules of Ada do not permit such an inconsistent program to be built.
-For example, if two clients have different versions of the same package,
-it is illegal to build a program containing these two clients.
-These rules are enforced by the GNAT binder, which also determines an
-elaboration order consistent with the Ada rules.
-
-The GNAT binder is run after all the object files for a program have
-been created. It is given the name of the main program unit, and from
-this it determines the set of units required by the program, by reading the
-corresponding ALI files. It generates error messages if the program is
-inconsistent or if no valid order of elaboration exists.
-
-If no errors are detected, the binder produces a main program, in Ada by
-default, that contains calls to the elaboration procedures of those
-compilation unit that require them, followed by
-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 @code{xxx} is the name of the
-main program unit.
-
-Finally, the linker is used to build the resulting executable program,
-using the object from the main program from the bind step as well as the
-object files for the Ada units of the program.
-
-@node GNAT and Libraries,Conditional Compilation,Binding an Ada Program,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-libraries}@anchor{2a}@anchor{gnat_ugn/the_gnat_compilation_model id35}@anchor{68}
-@section GNAT and Libraries
-
-
-@geindex Library building and using
-
-This section describes how to build and use libraries with GNAT, and also shows
-how to recompile the GNAT run-time library. You should be familiar with the
-Project Manager facility (see the `GNAT_Project_Manager' chapter of the
-`GPRbuild User’s Guide') before reading this chapter.
-
-@menu
-* Introduction to Libraries in GNAT:: 
-* General Ada Libraries:: 
-* Stand-alone Ada Libraries:: 
-* Rebuilding the GNAT Run-Time Library:: 
-
-@end menu
-
-@node Introduction to Libraries in GNAT,General Ada Libraries,,GNAT and Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id36}@anchor{69}@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-libraries-in-gnat}@anchor{6a}
-@subsection Introduction to Libraries in GNAT
-
-
-A library is, conceptually, a collection of objects which does not have its
-own main thread of execution, but rather provides certain services to the
-applications that use it. A library can be either statically linked with the
-application, in which case its code is directly included in the application,
-or, on platforms that support it, be dynamically linked, in which case
-its code is shared by all applications making use of this library.
-
-GNAT supports both types of libraries.
-In the static case, the compiled code can be provided in different ways. The
-simplest approach is to provide directly the set of objects resulting from
-compilation of the library source files. Alternatively, you can group the
-objects into an archive using whatever commands are provided by the operating
-system. For the latter case, the objects are grouped into a shared library.
-
-In the GNAT environment, a library has three types of components:
-
-
-@itemize *
-
-@item 
-Source files,
-
-@item 
-@code{ALI} files (see @ref{28,,The Ada Library Information Files}), and
-
-@item 
-Object files, an archive or a shared library.
-@end itemize
-
-A GNAT library may expose all its source files, which is useful for
-documentation purposes. Alternatively, it may expose only the units needed by
-an external user to make use of the library. That is to say, the specs
-reflecting the library services along with all the units needed to compile
-those specs, which can include generic bodies or any body implementing an
-inlined routine. In the case of `stand-alone libraries' those exposed
-units are called `interface units' (@ref{6b,,Stand-alone Ada Libraries}).
-
-All compilation units comprising an application, including those in a library,
-need to be elaborated in an order partially defined by Ada’s semantics. GNAT
-computes the elaboration order from the @code{ALI} files and this is why they
-constitute a mandatory part of GNAT libraries.
-`Stand-alone libraries' are the exception to this rule because a specific
-library elaboration routine is produced independently of the application(s)
-using the library.
-
-@node General Ada Libraries,Stand-alone Ada Libraries,Introduction to Libraries in GNAT,GNAT and Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model general-ada-libraries}@anchor{6c}@anchor{gnat_ugn/the_gnat_compilation_model id37}@anchor{6d}
-@subsection General Ada Libraries
-
-
-@menu
-* Building a library:: 
-* Installing a library:: 
-* Using a library:: 
-
-@end menu
-
-@node Building a library,Installing a library,,General Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model building-a-library}@anchor{6e}@anchor{gnat_ugn/the_gnat_compilation_model id38}@anchor{6f}
-@subsubsection Building a library
-
-
-The easiest way to build a library is to use the Project Manager,
-which supports a special type of project called a `Library Project'
-(see the `Library Projects' section in the `GNAT Project Manager'
-chapter of the `GPRbuild User’s Guide').
-
-A project is considered a library project, when two project-level attributes
-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:
-
-
-@itemize *
-
-@item 
-
-@table @asis
-
-@item @code{Library_Kind}
-
-This attribute controls whether the library is to be static or dynamic
-@end table
-
-@item 
-
-@table @asis
-
-@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
-installed versions of the binaries are compatible.
-@end table
-
-@item 
-@code{Library_Options}
-
-@item 
-
-@table @asis
-
-@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
-library.
-@end table
-@end itemize
-
-The GNAT Project Manager takes full care of the library maintenance task,
-including recompilation of the source files for which objects do not exist
-or are not up to date, assembly of the library archive, and installation of
-the library (i.e., copying associated source, object and @code{ALI} files
-to the specified location).
-
-Here is a simple library project file:
-
-@example
-project My_Lib is
-  for Source_Dirs use ("src1", "src2");
-  for Object_Dir use "obj";
-  for Library_Name use "mylib";
-  for Library_Dir use "lib";
-  for Library_Kind use "dynamic";
-end My_lib;
-@end example
-
-and the compilation command to build and install the library:
-
-@example
-$ gnatmake -Pmy_lib
-@end example
-
-It is not entirely trivial to perform manually all the steps required to
-produce a library. We recommend that you use the GNAT Project Manager
-for this task. In special cases where this is not desired, the necessary
-steps are discussed below.
-
-There are various possibilities for compiling the units that make up the
-library: for example with a Makefile (@ref{70,,Using the GNU make Utility}) or
-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
-@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.
-
-Here is an example of such a dummy program:
-
-@example
-with My_Lib.Service1;
-with My_Lib.Service2;
-with My_Lib.Service3;
-procedure My_Lib_Dummy is
-begin
-   null;
-end;
-@end example
-
-Here are the generic commands that will build an archive or a shared library.
-
-@example
-# compiling the library
-$ gnatmake -c my_lib_dummy.adb
-
-# we don't need the dummy object itself
-$ rm my_lib_dummy.o my_lib_dummy.ali
-
-# create an archive with the remaining objects
-$ ar rc libmy_lib.a *.o
-# some systems may require "ranlib" to be run as well
-
-# or create a shared library
-$ gcc -shared -o libmy_lib.so *.o
-# some systems may require the code to have been compiled with -fPIC
-
-# remove the object files that are now in the library
-$ rm *.o
-
-# Make the ALI files read-only so that gnatmake will not try to
-# regenerate the objects that are in the library
-$ chmod -w *.ali
-@end example
-
-Please note that the library must have a name of the form @code{lib`xxx'.a}
-or @code{lib`xxx'.so} (or @code{lib`xxx'.dll} on Windows) in order to
-be accessed by the directive @code{-l`xxx'} at link time.
-
-@node Installing a library,Using a library,Building a library,General Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id39}@anchor{71}@anchor{gnat_ugn/the_gnat_compilation_model installing-a-library}@anchor{72}
-@subsubsection Installing a library
-
-
-@geindex ADA_PROJECT_PATH
-
-@geindex GPR_PROJECT_PATH
-
-If you use project files, library installation is part of the library build
-process (see the `Installing a Library with Project Files' section of the
-`GNAT Project Manager' chapter of the `GPRbuild User’s Guide').
-
-When project files are not an option, it is also possible, but not recommended,
-to install the library so that the sources needed to use the library are on the
-Ada source path and the ALI files & libraries be on the Ada Object path (see
-@ref{73,,Search Paths and the Run-Time Library (RTL)}. Alternatively, the system
-administrator can place general-purpose libraries in the default compiler
-paths, by specifying the libraries’ location in the configuration files
-@code{ada_source_path} and @code{ada_object_path}. These configuration files
-must be located in the GNAT installation tree at the same place as the gcc spec
-file. The location of the gcc spec file can be determined as follows:
-
-@example
-$ gcc -v
-@end example
-
-The configuration files mentioned above have a simple format: each line
-must contain one unique directory name.
-Those names are added to the corresponding path
-in their order of appearance in the file. The names can be either absolute
-or relative; in the latter case, they are relative to where theses files
-are located.
-
-The files @code{ada_source_path} and @code{ada_object_path} might not be
-present in a
-GNAT installation, in which case, GNAT will look for its run-time library in
-the directories @code{adainclude} (for the sources) and @code{adalib} (for the
-objects and @code{ALI} files). When the files exist, the compiler does not
-look in @code{adainclude} and @code{adalib}, and thus the
-@code{ada_source_path} file
-must contain the location for the GNAT run-time sources (which can simply
-be @code{adainclude}). In the same way, the @code{ada_object_path} file must
-contain the location for the GNAT run-time objects (which can simply
-be @code{adalib}).
-
-You can also specify a new default path to the run-time library at compilation
-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 @code{gcc}, @code{gnatmake}, @code{gnatbind}, @code{gnatls}, and all
-project aware tools.
-
-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
-library must be installed before the GNAT library if it redefines
-any part of it.
-
-@node Using a library,,Installing a library,General Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id40}@anchor{74}@anchor{gnat_ugn/the_gnat_compilation_model using-a-library}@anchor{75}
-@subsubsection Using a library
-
-
-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 @code{My_Lib} shown in examples in earlier sections, you can
-write:
-
-@example
-with "my_lib";
-project My_Proj is
-  ...
-end My_Proj;
-@end example
-
-Even if you have a third-party, non-Ada library, you can still use GNAT’s
-Project Manager facility to provide a wrapper for it. For example, the
-following project, when `with'ed by your main project, will link with the
-third-party library @code{liba.a}:
-
-@example
-project Liba is
-   for Externally_Built use "true";
-   for Source_Files use ();
-   for Library_Dir use "lib";
-   for Library_Name use "a";
-   for Library_Kind use "static";
-end Liba;
-@end example
-
-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.
-
-In order to use an Ada library manually, you need to make sure that this
-library is on both your source and object path
-(see @ref{73,,Search Paths and the Run-Time Library (RTL)}
-and @ref{76,,Search Paths for gnatbind}). Furthermore, when the objects are grouped
-in an archive or a shared library, you need to specify the desired
-library at link time.
-
-For example, you can use the library @code{mylib} installed in
-@code{/dir/my_lib_src} and @code{/dir/my_lib_obj} with the following commands:
-
-@example
-$ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \\
-  -largs -lmy_lib
-@end example
-
-This can be expressed more simply:
-
-@example
-$ gnatmake my_appl
-@end example
-
-when the following conditions are met:
-
-
-@itemize *
-
-@item 
-@code{/dir/my_lib_src} has been added by the user to the environment
-variable 
-@geindex ADA_INCLUDE_PATH
-@geindex environment variable; ADA_INCLUDE_PATH
-@code{ADA_INCLUDE_PATH}, or by the administrator to the file
-@code{ada_source_path}
-
-@item 
-@code{/dir/my_lib_obj} has been added by the user to the environment
-variable 
-@geindex ADA_OBJECTS_PATH
-@geindex environment variable; ADA_OBJECTS_PATH
-@code{ADA_OBJECTS_PATH}, or by the administrator to the file
-@code{ada_object_path}
-
-@item 
-a pragma @code{Linker_Options} has been added to one of the sources.
-For example:
-
-@example
-pragma Linker_Options ("-lmy_lib");
-@end example
-@end itemize
-
-Note that you may also load a library dynamically at
-run time given its filename, as illustrated in the GNAT @code{plugins} example
-in the directory @code{share/examples/gnat/plugins} within the GNAT
-install area.
-
-@node Stand-alone Ada Libraries,Rebuilding the GNAT Run-Time Library,General Ada Libraries,GNAT and Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id41}@anchor{77}@anchor{gnat_ugn/the_gnat_compilation_model stand-alone-ada-libraries}@anchor{6b}
-@subsection Stand-alone Ada Libraries
-
-
-@geindex Stand-alone libraries
-
-@menu
-* Introduction to Stand-alone Libraries:: 
-* Building a Stand-alone Library:: 
-* Creating a Stand-alone Library to be used in a non-Ada context:: 
-* Restrictions in Stand-alone Libraries:: 
-
-@end menu
-
-@node Introduction to Stand-alone Libraries,Building a Stand-alone Library,,Stand-alone Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id42}@anchor{78}@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-stand-alone-libraries}@anchor{79}
-@subsubsection Introduction to Stand-alone Libraries
-
-
-A Stand-alone Library (abbreviated ‘SAL’) is a library that contains the
-necessary code to
-elaborate the Ada units that are included in the library. In contrast with
-an ordinary library, which consists of all sources, objects and @code{ALI}
-files of the
-library, a SAL may specify a restricted subset of compilation units
-to serve as a library interface. In this case, the fully
-self-sufficient set of files will normally consist of an objects
-archive, the sources of interface units’ specs, and the @code{ALI}
-files of interface units.
-If an interface spec contains a generic unit or an inlined subprogram,
-the body’s
-source must also be provided; if the units that must be provided in the source
-form depend on other units, the source and @code{ALI} files of those must
-also be provided.
-
-The main purpose of a SAL is to minimize the recompilation overhead of client
-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 @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
-text exposed to the clients.  Such ‘information hiding’ might be useful or
-necessary for various reasons.
-
-Stand-alone libraries are also well suited to be used in an executable whose
-main routine is not written in Ada.
-
-@node Building a Stand-alone Library,Creating a Stand-alone Library to be used in a non-Ada context,Introduction to Stand-alone Libraries,Stand-alone Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model building-a-stand-alone-library}@anchor{7a}@anchor{gnat_ugn/the_gnat_compilation_model id43}@anchor{7b}
-@subsubsection Building a Stand-alone Library
-
-
-GNAT’s Project facility provides a simple way of building and installing
-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 (@code{Library_Name} and
-@code{Library_Dir}; see the `Library Projects' section in the
-`GNAT Project Manager' chapter of the `GPRbuild User’s Guide'),
-the attribute @code{Library_Interface} must be defined.  For example:
-
-@example
-for Library_Dir use "lib_dir";
-for Library_Name use "dummy";
-for Library_Interface use ("int1", "int1.child");
-@end example
-
-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.
-
-When a Stand-alone Library is built, first the binder is invoked to build
-a package whose name depends on the library name
-(@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 (@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 @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 @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.
-
-It is also possible to build an encapsulated library where not only
-the code to elaborate and finalize the library is embedded but also
-ensuring that the library is linked only against static
-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
-@code{Library_Standalone} must be set to @code{encapsulated}:
-
-@example
-for Library_Dir use "lib_dir";
-for Library_Name use "dummy";
-for Library_Kind use "dynamic";
-for Library_Interface use ("int1", "int1.child");
-for Library_Standalone use "encapsulated";
-@end example
-
-The default value for this attribute is @code{standard} in which case
-a stand-alone library is built.
-
-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
-the library directory. The sources of the Interface
-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 @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.
-
-Building stand-alone libraries by hand is somewhat tedious, but for those
-occasions when it is necessary here are the steps that you need to perform:
-
-
-@itemize *
-
-@item 
-Compile all library sources.
-
-@item 
-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 @code{-L} to give specific names to the @code{init}
-and @code{final} procedures.  For example:
-
-@example
-$ gnatbind -n int1.ali int2.ali -Lsal1
-@end example
-
-@item 
-Compile the binder generated file:
-
-@example
-$ gcc -c b~int2.adb
-@end example
-
-@item 
-Link the dynamic library with all the necessary object files,
-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 @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 @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
-
-Using SALs is not different from using other libraries
-(see @ref{75,,Using a library}).
-
-@node Creating a Stand-alone Library to be used in a non-Ada context,Restrictions in Stand-alone Libraries,Building a Stand-alone Library,Stand-alone Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model creating-a-stand-alone-library-to-be-used-in-a-non-ada-context}@anchor{7c}@anchor{gnat_ugn/the_gnat_compilation_model id44}@anchor{7d}
-@subsubsection Creating a Stand-alone Library to be used in a non-Ada context
-
-
-It is easy to adapt the SAL build procedure discussed above for use of a SAL in
-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 @code{pragma Export}
-or @code{pragma Convention}.
-
-Here is an example of simple library interface for use with C main program:
-
-@example
-package My_Package is
-
-   procedure Do_Something;
-   pragma Export (C, Do_Something, "do_something");
-
-   procedure Do_Something_Else;
-   pragma Export (C, Do_Something_Else, "do_something_else");
-
-end My_Package;
-@end example
-
-On the foreign language side, you must provide a ‘foreign’ view of the
-library interface; remember that it should contain elaboration routines in
-addition to interface subprograms.
-
-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
-/* the library elaboration procedure */
-extern void mylibinit (void);
-
-/* the library finalization procedure */
-extern void mylibfinal (void);
-
-/* the interface exported by the library */
-extern void do_something (void);
-extern void do_something_else (void);
-@end example
-
-Libraries built as explained above can be used from any program, provided
-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 @code{mylib} library.
-
-@example
-#include "mylib_interface.h"
-
-int
-main (void)
-@{
-   /* First, elaborate the library before using it */
-   mylibinit ();
-
-   /* Main program, using the library exported entities */
-   do_something ();
-   do_something_else ();
-
-   /* Library finalization at the end of the program */
-   mylibfinal ();
-   return 0;
-@}
-@end example
-
-Note that invoking any library finalization procedure generated by
-@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
-after the finalization phase.
-
-Note also that special care must be taken with multi-tasks
-applications. The initialization and finalization routines are not
-protected against concurrent access. If such requirement is needed it
-must be ensured at the application level using a specific operating
-system services like a mutex or a critical-section.
-
-@node Restrictions in Stand-alone Libraries,,Creating a Stand-alone Library to be used in a non-Ada context,Stand-alone Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id45}@anchor{7e}@anchor{gnat_ugn/the_gnat_compilation_model restrictions-in-stand-alone-libraries}@anchor{7f}
-@subsubsection Restrictions in Stand-alone Libraries
-
-
-The pragmas listed below should be used with caution inside libraries,
-as they can create incompatibilities with other Ada libraries:
-
-
-@itemize *
-
-@item 
-pragma @code{Locking_Policy}
-
-@item 
-pragma @code{Partition_Elaboration_Policy}
-
-@item 
-pragma @code{Queuing_Policy}
-
-@item 
-pragma @code{Task_Dispatching_Policy}
-
-@item 
-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,
-@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.
-
-Similarly, the traceback in the exception occurrence mechanism should be
-enabled or disabled in a consistent manner across all libraries.
-Otherwise, Program_Error will be raised during the elaboration of the
-conflicting libraries.
-
-If the @code{Version} or @code{Body_Version}
-attributes are used inside a library, then you need to
-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.
-
-@node Rebuilding the GNAT Run-Time Library,,Stand-alone Ada Libraries,GNAT and Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id46}@anchor{80}@anchor{gnat_ugn/the_gnat_compilation_model rebuilding-the-gnat-run-time-library}@anchor{81}
-@subsection Rebuilding the GNAT Run-Time Library
-
-
-@geindex GNAT Run-Time Library
-@geindex rebuilding
-
-@geindex Building the GNAT Run-Time Library
-
-@geindex Rebuilding the GNAT Run-Time Library
-
-@geindex Run-Time Library
-@geindex rebuilding
-
-It may be useful to recompile the GNAT library in various debugging or
-experimentation contexts. A project file called
-@code{libada.gpr} 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:
-
-@example
-$ gnatls -v
-@end example
-
-The last entry in the source search path usually contains the
-gnat library (the @code{adainclude} directory). This project file contains its
-own documentation and in particular the set of instructions needed to rebuild a
-new library and to use it.
-
-Note that rebuilding the GNAT Run-Time is only recommended for temporary
-experiments or debugging, and is not supported.
-
-@geindex Conditional compilation
-
-@node Conditional Compilation,Mixed Language Programming,GNAT and Libraries,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model conditional-compilation}@anchor{2b}@anchor{gnat_ugn/the_gnat_compilation_model id47}@anchor{82}
-@section Conditional Compilation
-
-
-This section presents some guidelines for modeling conditional compilation in Ada and describes the
-gnatprep preprocessor utility.
-
-@geindex Conditional compilation
-
-@menu
-* Modeling Conditional Compilation in Ada:: 
-* Preprocessing with gnatprep:: 
-* Integrated Preprocessing:: 
-
-@end menu
-
-@node Modeling Conditional Compilation in Ada,Preprocessing with gnatprep,,Conditional Compilation
-@anchor{gnat_ugn/the_gnat_compilation_model id48}@anchor{83}@anchor{gnat_ugn/the_gnat_compilation_model modeling-conditional-compilation-in-ada}@anchor{84}
-@subsection Modeling Conditional Compilation in Ada
-
-
-It is often necessary to arrange for a single source program
-to serve multiple purposes, where it is compiled in different
-ways to achieve these different goals. Some examples of the
-need for this feature are
-
-
-@itemize *
-
-@item 
-Adapting a program to a different hardware environment
-
-@item 
-Adapting a program to a different target architecture
-
-@item 
-Turning debugging features on and off
-
-@item 
-Arranging for a program to compile with different compilers
-@end itemize
-
-In C, or C++, the typical approach would be to use the preprocessor
-that is defined as part of the language. The Ada language does not
-contain such a feature. This is not an oversight, but rather a very
-deliberate design decision, based on the experience that overuse of
-the preprocessing features in C and C++ can result in programs that
-are extremely difficult to maintain. For example, if we have ten
-switches that can be on or off, this means that there are a thousand
-separate programs, any one of which might not even be syntactically
-correct, and even if syntactically correct, the resulting program
-might not work correctly. Testing all combinations can quickly become
-impossible.
-
-Nevertheless, the need to tailor programs certainly exists, and in
-this section we will discuss how this can
-be achieved using Ada in general, and GNAT in particular.
-
-@menu
-* Use of Boolean Constants:: 
-* Debugging - A Special Case:: 
-* Conditionalizing Declarations:: 
-* Use of Alternative Implementations:: 
-* Preprocessing:: 
-
-@end menu
-
-@node Use of Boolean Constants,Debugging - A Special Case,,Modeling Conditional Compilation in Ada
-@anchor{gnat_ugn/the_gnat_compilation_model id49}@anchor{85}@anchor{gnat_ugn/the_gnat_compilation_model use-of-boolean-constants}@anchor{86}
-@subsubsection Use of Boolean Constants
-
-
-In the case where the difference is simply which code
-sequence is executed, the cleanest solution is to use Boolean
-constants to control which code is executed.
-
-@example
-FP_Initialize_Required : constant Boolean := True;
-...
-if FP_Initialize_Required then
-...
-end if;
-@end example
-
-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 @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
-is turned on.)
-
-@geindex Preprocessors (contrasted with conditional compilation)
-
-Typically the Boolean constants will be in a separate package,
-something like:
-
-@example
-package Config is
-   FP_Initialize_Required : constant Boolean := True;
-   Reset_Available        : constant Boolean := False;
-   ...
-end Config;
-@end example
-
-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 `with'
-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{87}@anchor{gnat_ugn/the_gnat_compilation_model id50}@anchor{88}
-@subsubsection Debugging - A Special Case
-
-
-A common use of conditional code is to execute statements (for example
-dynamic checks, or output of intermediate results) under control of a
-debug switch, so that the debugging behavior can be turned on and off.
-This can be done using a Boolean constant to control whether the code
-is active:
-
-@example
-if Debugging then
-   Put_Line ("got to the first stage!");
-end if;
-@end example
-
-or
-
-@example
-if Debugging and then Temperature > 999.0 then
-   raise Temperature_Crazy;
-end if;
-@end example
-
-@geindex pragma Assert
-
-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 @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 @code{Assert} is described in the
-@cite{GNAT_Reference_Manual}, but as an
-example, the last test could be written:
-
-@example
-pragma Assert (Temperature <= 999.0, "Temperature Crazy");
-@end example
-
-or simply
-
-@example
-pragma Assert (Temperature <= 999.0);
-@end example
-
-In both cases, if assertions are active and the temperature is excessive,
-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 @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 @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 @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, @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 @code{Debug} argument as needed.
-
-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 @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 @code{Assertion_Policy} to control assertions.
-
-@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 @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 @code{null} statement.
-
-@example
-if ... then
-   ... -- some statements
-else
-   pragma Assert (Num_Cases < 10);
-   null;
-end if;
-@end example
-
-@node Conditionalizing Declarations,Use of Alternative Implementations,Debugging - A Special Case,Modeling Conditional Compilation in Ada
-@anchor{gnat_ugn/the_gnat_compilation_model conditionalizing-declarations}@anchor{89}@anchor{gnat_ugn/the_gnat_compilation_model id51}@anchor{8a}
-@subsubsection Conditionalizing Declarations
-
-
-In some cases it may be necessary to conditionalize declarations to meet
-different requirements. For example we might want a bit string whose length
-is set to meet some hardware message requirement.
-
-This may be possible using declare blocks controlled
-by conditional constants:
-
-@example
-if Small_Machine then
-   declare
-      X : Bit_String (1 .. 10);
-   begin
-      ...
-   end;
-else
-   declare
-      X : Large_Bit_String (1 .. 1000);
-   begin
-      ...
-   end;
-end if;
-@end example
-
-Note that in this approach, both declarations are analyzed by the
-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., @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
-for Rec use
-  Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word;
-end record;
-@end example
-
-If @code{Bits_Per_Word} is set to 32, this generates either
-
-@example
-for Rec use
-  Field1 at 0 range 0 .. 32;
-end record;
-@end example
-
-for the big endian case, or
-
-@example
-for Rec use record
-    Field1 at 0 range 10 .. 32;
-end record;
-@end example
-
-for the little endian case. Since a powerful subset of Ada expression
-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 @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
-@anchor{gnat_ugn/the_gnat_compilation_model id52}@anchor{8b}@anchor{gnat_ugn/the_gnat_compilation_model use-of-alternative-implementations}@anchor{8c}
-@subsubsection Use of Alternative Implementations
-
-
-In some cases, none of the approaches described above are adequate. This
-can occur for example if the set of declarations required is radically
-different for two different configurations.
-
-In this situation, the official Ada way of dealing with conditionalizing
-such code is to write separate units for the different cases. As long as
-this does not result in excessive duplication of code, this can be done
-without creating maintenance problems. The approach is to share common
-code as far as possible, and then isolate the code and declarations
-that are different. Subunits are often a convenient method for breaking
-out a piece of a unit that is to be conditionalized, with separate files
-for different versions of the subunit for different targets, where the
-build script selects the right one to give to the compiler.
-
-@geindex Subunits (and conditional compilation)
-
-As an example, consider a situation where a new feature in Ada 2005
-allows something to be done in a really nice way. But your code must be able
-to compile with an Ada 95 compiler. Conceptually you want to say:
-
-@example
-if Ada_2005 then
-   ... neat Ada 2005 code
-else
-   ... not quite as neat Ada 95 code
-end if;
-@end example
-
-where @code{Ada_2005} is a Boolean constant.
-
-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.)
-
-So instead we write
-
-@example
-procedure Insert is separate;
-@end example
-
-Then we have two files for the subunit @code{Insert}, with the two sets of
-code.
-If the package containing this is called @code{File_Queries}, then we might
-have two files
-
-
-@itemize *
-
-@item 
-@code{file_queries-insert-2005.adb}
-
-@item 
-@code{file_queries-insert-95.adb}
-@end itemize
-
-and the build script renames the appropriate file to @code{file_queries-insert.adb} and then carries out the compilation.
-
-This can also be done with project files’ naming schemes. For example:
-
-@example
-for body ("File_Queries.Insert") use "file_queries-insert-2005.ada";
-@end example
-
-Note also that with project files it is desirable to use a different extension
-than @code{ads} / @code{adb} for alternative versions. Otherwise a naming
-conflict may arise through another commonly used feature: to declare as part
-of the project a set of directories containing all the sources obeying the
-default naming scheme.
-
-The use of alternative units is certainly feasible in all situations,
-and for example the Ada part of the GNAT run-time is conditionalized
-based on the target architecture using this approach. As a specific example,
-consider the implementation of the AST feature in VMS. There is one
-spec: @code{s-asthan.ads} which is the same for all architectures, and three
-bodies:
-
-
-@itemize *
-
-@item 
-
-@table @asis
-
-@item @code{s-asthan.adb}
-
-used for all non-VMS operating systems
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{s-asthan-vms-alpha.adb}
-
-used for VMS on the Alpha
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{s-asthan-vms-ia64.adb}
-
-used for VMS on the ia64
-@end table
-@end itemize
-
-The dummy version @code{s-asthan.adb} simply raises exceptions noting that
-this operating system feature is not available, and the two remaining
-versions interface with the corresponding versions of VMS to provide
-VMS-compatible AST handling. The GNAT build script knows the architecture
-and operating system, and automatically selects the right version,
-renaming it if necessary to @code{s-asthan.adb} before the run-time build.
-
-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 @code{Ref} that is initialized
-to designate a ‘do nothing’ procedure, and then invoke @code{Ref.all}
-when appropriate.
-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
-calls.
-
-@node Preprocessing,,Use of Alternative Implementations,Modeling Conditional Compilation in Ada
-@anchor{gnat_ugn/the_gnat_compilation_model id53}@anchor{8d}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing}@anchor{8e}
-@subsubsection Preprocessing
-
-
-@geindex Preprocessing
-
-Although it is quite possible to conditionalize code without the use of
-C-style preprocessing, as described earlier in this section, it is
-nevertheless convenient in some cases to use the C approach. Moreover,
-older Ada compilers have often provided some preprocessing capability,
-so legacy code may depend on this approach, even though it is not
-standard.
-
-To accommodate such use, GNAT provides a preprocessor (modeled to a large
-extent on the various preprocessors that have been used
-with legacy code on other compilers, to enable easier transition).
-
-@geindex gnatprep
-
-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
-@code{gnatprep} utility, whose use is fully described in
-@ref{8f,,Preprocessing with gnatprep}.
-
-The preprocessing language allows such constructs as
-
-@example
-#if DEBUG or else (PRIORITY > 4) then
-   sequence of declarations
-#else
-   completely different sequence of declarations
-#end if;
-@end example
-
-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 @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{90,,Integrated Preprocessing}.
-
-@node Preprocessing with gnatprep,Integrated Preprocessing,Modeling Conditional Compilation in Ada,Conditional Compilation
-@anchor{gnat_ugn/the_gnat_compilation_model id54}@anchor{91}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-with-gnatprep}@anchor{8f}
-@subsection Preprocessing with @code{gnatprep}
-
-
-@geindex gnatprep
-
-@geindex Preprocessing (gnatprep)
-
-This section discusses how to use GNAT’s @code{gnatprep} utility for simple
-preprocessing.
-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{2b,,Conditional Compilation}.
-
-@menu
-* Preprocessing Symbols:: 
-* Using gnatprep:: 
-* Switches for gnatprep:: 
-* Form of Definitions File:: 
-* Form of Input Text for gnatprep:: 
-
-@end menu
-
-@node Preprocessing Symbols,Using gnatprep,,Preprocessing with gnatprep
-@anchor{gnat_ugn/the_gnat_compilation_model id55}@anchor{92}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-symbols}@anchor{93}
-@subsubsection Preprocessing Symbols
-
-
-Preprocessing symbols are defined in `definition files' and referenced in the
-sources to be preprocessed. A preprocessing symbol is an identifier, following
-normal Ada (case-insensitive) rules for its syntax, with the restriction that
-all characters need to be in the ASCII set (no accented letters).
-
-@node Using gnatprep,Switches for gnatprep,Preprocessing Symbols,Preprocessing with gnatprep
-@anchor{gnat_ugn/the_gnat_compilation_model id56}@anchor{94}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatprep}@anchor{95}
-@subsubsection Using @code{gnatprep}
-
-
-To call @code{gnatprep} use:
-
-@example
-$ gnatprep [ switches ] infile outfile [ deffile ]
-@end example
-
-where
-
-
-@itemize *
-
-@item 
-
-@table @asis
-
-@item `switches'
-
-is an optional sequence of switches as described in the next section.
-@end table
-
-@item 
-
-@table @asis
-
-@item `infile'
-
-is the full name of the input file, which is an Ada source
-file containing preprocessor directives.
-@end table
-
-@item 
-
-@table @asis
-
-@item `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 @code{ads} or @code{adb} suffix.
-@end table
-
-@item 
-
-@table @asis
-
-@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 @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 id57}@anchor{96}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatprep}@anchor{97}
-@subsubsection Switches for @code{gnatprep}
-
-
-@geindex --version (gnatprep)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display Copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatprep)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage and then exit disregarding
-all other options.
-@end table
-
-@geindex -b (gnatprep)
-
-
-@table @asis
-
-@item @code{-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.
-@end table
-
-@geindex -c (gnatprep)
-
-
-@table @asis
-
-@item @code{-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 @code{"--! "}. This option will result in line numbers
-being preserved in the output file.
-@end table
-
-@geindex -C (gnatprep)
-
-
-@table @asis
-
-@item @code{-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
-when structured comments are used (e.g., for programs written in a
-pre-2014 version of the SPARK Ada subset). Note that this switch is not
-available when  doing integrated preprocessing (it would be useless in
-this context since comments are ignored by the compiler in any case).
-@end table
-
-@geindex -D (gnatprep)
-
-
-@table @asis
-
-@item @code{-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 @code{True}. This switch
-can be used in place of a definition file.
-@end table
-
-@geindex -r (gnatprep)
-
-
-@table @asis
-
-@item @code{-r}
-
-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 @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 @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
-@code{gnatchop -r}
-so that the final chopped files will correctly refer to the original
-input source file for @code{gnatprep}.
-@end table
-
-@geindex -s (gnatprep)
-
-
-@table @asis
-
-@item @code{-s}
-
-Causes a sorted list of symbol names and values to be
-listed on the standard output file.
-@end table
-
-@geindex -T (gnatprep)
-
-
-@table @asis
-
-@item @code{-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.
-@end table
-
-@geindex -u (gnatprep)
-
-
-@table @asis
-
-@item @code{-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 @code{#if} or @code{#elsif} test will be treated as an error.
-@end table
-
-@geindex -v (gnatprep)
-
-
-@table @asis
-
-@item @code{-v}
-
-Verbose mode: generates more output about work done.
-@end table
-
-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.
-
-@node Form of Definitions File,Form of Input Text for gnatprep,Switches for gnatprep,Preprocessing with gnatprep
-@anchor{gnat_ugn/the_gnat_compilation_model form-of-definitions-file}@anchor{98}@anchor{gnat_ugn/the_gnat_compilation_model id58}@anchor{99}
-@subsubsection Form of Definitions File
-
-
-The definitions file contains lines of the form:
-
-@example
-symbol := value
-@end example
-
-where @code{symbol} is a preprocessing symbol, and @code{value} is one of the following:
-
-
-@itemize *
-
-@item 
-Empty, corresponding to a null substitution,
-
-@item 
-A string literal using normal Ada syntax, or
-
-@item 
-Any sequence of characters from the set @{letters, digits, period, underline@}.
-@end itemize
-
-Comment lines may also appear in the definitions file, starting with
-the usual @code{--},
-and comments may be added to the definitions lines.
-
-@node Form of Input Text for gnatprep,,Form of Definitions File,Preprocessing with gnatprep
-@anchor{gnat_ugn/the_gnat_compilation_model form-of-input-text-for-gnatprep}@anchor{9a}@anchor{gnat_ugn/the_gnat_compilation_model id59}@anchor{9b}
-@subsubsection Form of Input Text for @code{gnatprep}
-
-
-The input text may contain preprocessor conditional inclusion lines,
-as well as general symbol substitution sequences.
-
-The preprocessor conditional inclusion commands have the form:
-
-@example
-#if <expression> [then]
-   lines
-#elsif <expression> [then]
-   lines
-#elsif <expression> [then]
-   lines
-...
-#else
-   lines
-#end if;
-@end example
-
-In this example, <expression> is defined by the following grammar:
-
-@example
-<expression> ::=  <symbol>
-<expression> ::=  <symbol> = "<value>"
-<expression> ::=  <symbol> = <symbol>
-<expression> ::=  <symbol> = <integer>
-<expression> ::=  <symbol> > <integer>
-<expression> ::=  <symbol> >= <integer>
-<expression> ::=  <symbol> < <integer>
-<expression> ::=  <symbol> <= <integer>
-<expression> ::=  <symbol> 'Defined
-<expression> ::=  not <expression>
-<expression> ::=  <expression> and <expression>
-<expression> ::=  <expression> or <expression>
-<expression> ::=  <expression> and then <expression>
-<expression> ::=  <expression> or else <expression>
-<expression> ::=  ( <expression> )
-@end example
-
-Note the following restriction: it is not allowed to have “and” or “or”
-following “not” in the same expression without parentheses. For example, this
-is not allowed:
-
-@example
-not X or Y
-@end example
-
-This can be expressed instead as one of the following forms:
-
-@example
-(not X) or Y
-not (X or Y)
-@end example
-
-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
-@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.
-
-When comparing a symbol to an integer, the integer is any non negative
-literal integer as defined in the Ada Reference Manual, such as 3, 16#FF# or
-2#11#. The symbol value must also be a non negative integer. Integer values
-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 @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 @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 @code{True}
-or @code{False}.
-
-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 @code{then} keyword is optional as shown
-
-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 @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 @code{elsif} clauses can be present,
-including none at all. The @code{else} is optional, as in Ada.
-
-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.
-
-Symbol substitution outside of preprocessor lines is obtained by using
-the sequence:
-
-@example
-$symbol
-@end example
-
-anywhere within a source line, except in a comment or within a
-string literal. The identifier
-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 @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 @code{hello} and writing:
-
-@example
-Header : String := "$XYZ";
-@end example
-
-you should set XYZ to @code{"hello"} and write:
-
-@example
-Header : String := $XYZ;
-@end example
-
-and then the substitution will occur as desired.
-
-@node Integrated Preprocessing,,Preprocessing with gnatprep,Conditional Compilation
-@anchor{gnat_ugn/the_gnat_compilation_model id60}@anchor{9c}@anchor{gnat_ugn/the_gnat_compilation_model integrated-preprocessing}@anchor{90}
-@subsection Integrated Preprocessing
-
-
-As noted above, a file to be preprocessed consists of Ada source code
-in which preprocessing lines have been inserted. However,
-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 `integrated preprocessing', which is the common
-style with C, is performed when either or both of the following switches
-are passed to the compiler:
-
-@quotation
-
-
-@itemize *
-
-@item 
-@code{-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).
-
-@item 
-@code{-gnateD}, which defines values for preprocessing symbols.
-@end itemize
-@end quotation
-
-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 @code{gnatprep}
-in standalone mode or else supply the @code{-gnateG} switch
-(described below) to the compiler.
-
-When using project files:
-
-@quotation
-
-
-@itemize *
-
-@item 
-the builder switch @code{-x} should be used if any Ada source is
-compiled with @code{gnatep=}, so that the compiler finds the
-`preprocessor data file'.
-
-@item 
-the preprocessing data file and the symbol definition files should be
-located in the source directories of the project.
-@end itemize
-@end quotation
-
-Note that the @code{gnatmake} switch @code{-m} will almost
-always trigger recompilation for sources that are preprocessed,
-because @code{gnatmake} cannot compute the checksum of the source after
-preprocessing.
-
-The actual preprocessing function is described in detail in
-@ref{8f,,Preprocessing with gnatprep}. This section explains the switches
-that relate to integrated preprocessing.
-
-@geindex -gnatep (gcc)
-
-
-@table @asis
-
-@item @code{-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
-files, reference the project file’s directory via the
-@code{project_name'Project_Dir} project attribute; e.g:
-
-@quotation
-
-@example
-project Prj is
-   package Compiler is
-      for Switches ("Ada") use
-        ("-gnatep=" & Prj'Project_Dir & "prep.def");
-   end Compiler;
-end Prj;
-@end example
-@end quotation
-
-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 @code{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
-preprocessor symbols, as well as a list of switches that relate to
-preprocessing.
-Empty lines and comments (using Ada syntax) are also permitted, with no
-semantic effect.
-
-Here’s an example of a preprocessor data file:
-
-@quotation
-
-@example
-"toto.adb"  "prep.def" -u
---  Preprocess toto.adb, using definition file prep.def
---  Undefined symbols are treated as False
-
-* -c -DVERSION=V101
---  Preprocess all other sources without using a definition file
---  Suppressed lined are commented
---  Symbol VERSION has the value V101
-
-"tata.adb" "prep2.def" -s
---  Preprocess tata.adb, using definition file prep2.def
---  List all symbols with their values
-@end example
-@end quotation
-
-A preprocessor control line has the following syntax:
-
-@quotation
-
-@example
-<preprocessor_control_line> ::=
-   <preprocessor_input> [ <definition_file_name> ] @{ <switch> @}
-
-<preprocessor_input> ::= <source_file_name> | '*'
-
-<definition_file_name> ::= <string_literal>
-
-<source_file_name> := <string_literal>
-
-<switch> := (See below for list)
-@end example
-@end quotation
-
-Thus  each preprocessor control line starts with either a literal string or
-the character ‘*’:
-
-
-@itemize *
-
-@item 
-A literal string is the file name (without directory information) of the source
-file that will be input to the preprocessor.
-
-@item 
-The character ‘*’ is a wild-card indicator; the additional parameters on the line
-indicate the preprocessing for all the sources
-that are not specified explicitly on other lines (the order of the lines is not
-significant).
-@end itemize
-
-It is an error to have two lines with the same file name or two
-lines starting with the character ‘*’.
-
-After the file name or ‘*’, an optional literal string specifies the name of
-the definition file to be used for preprocessing
-(@ref{98,,Form of Definitions File}). The definition files are found by the
-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 @code{-I} switch; otherwise
-the compiler would not find the definition file.
-
-Finally, switches similar to those of @code{gnatprep} may optionally appear:
-
-
-@table @asis
-
-@item @code{-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 @code{-c}
-it cancels the effect of @code{-c}.
-
-@item @code{-c}
-
-Causes both preprocessor lines and the lines deleted
-by preprocessing to be retained as comments marked
-with the special string ‘@cite{–!}’.
-
-@item @code{-D`symbol'=`new_value'}
-
-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{-s}
-
-Causes a sorted list of symbol names and values to be
-listed on the standard output file.
-
-@item @code{-u}
-
-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 @code{#if} or @code{#elsif} test will be treated as an error.
-@end table
-@end table
-
-@geindex -gnateD (gcc)
-
-
-@table @asis
-
-@item @code{-gnateD`symbol'[=`new_value']}
-
-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 @code{if},
-@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}.
-
-Examples:
-
-@quotation
-
-@example
--gnateDToto=Tata
--gnateDFoo
--gnateDFoo=\"Foo-Bar\"
-@end example
-@end quotation
-
-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 @code{-D} in the preprocessor data file.
-
-This switch is similar to switch @code{-D} of @code{gnatprep}.
-
-@item @code{-gnateG}
-
-When integrated preprocessing is performed on source file @code{filename.extension},
-create or overwrite @code{filename.extension.prep} to contain
-the result of the preprocessing.
-For example if the source file is @code{foo.adb} then
-the output file will be @code{foo.adb.prep}.
-@end table
-
-@node Mixed Language Programming,GNAT and Other Compilation Models,Conditional Compilation,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id61}@anchor{9d}@anchor{gnat_ugn/the_gnat_compilation_model mixed-language-programming}@anchor{2c}
-@section Mixed Language Programming
-
-
-@geindex Mixed Language Programming
-
-This section describes how to develop a mixed-language program,
-with a focus on combining Ada with C or C++.
-
-@menu
-* Interfacing to C:: 
-* Calling Conventions:: 
-* Building Mixed Ada and C++ Programs:: 
-* Generating Ada Bindings for C and C++ headers:: 
-* Generating C Headers for Ada Specifications:: 
-
-@end menu
-
-@node Interfacing to C,Calling Conventions,,Mixed Language Programming
-@anchor{gnat_ugn/the_gnat_compilation_model id62}@anchor{9e}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-to-c}@anchor{9f}
-@subsection Interfacing to C
-
-
-Interfacing Ada with a foreign language such as C involves using
-compiler directives to import and/or export entity definitions in each
-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.
-
-There are two ways to build a program using GNAT that contains some Ada
-sources and some foreign language sources, depending on whether or not
-the main subprogram is written in Ada.  Here is a source example with
-the main subprogram in Ada:
-
-@example
-/* file1.c */
-#include <stdio.h>
-
-void print_num (int num)
-@{
-  printf ("num is %d.\\n", num);
-  return;
-@}
-@end example
-
-@example
-/* file2.c */
-
-/* num_from_Ada is declared in my_main.adb */
-extern int num_from_Ada;
-
-int get_num (void)
-@{
-  return num_from_Ada;
-@}
-@end example
-
-@example
---  my_main.adb
-procedure My_Main is
-
-   --  Declare then export an Integer entity called num_from_Ada
-   My_Num : Integer := 10;
-   pragma Export (C, My_Num, "num_from_Ada");
-
-   --  Declare an Ada function spec for Get_Num, then use
-   --  C function get_num for the implementation.
-   function Get_Num return Integer;
-   pragma Import (C, Get_Num, "get_num");
-
-   --  Declare an Ada procedure spec for Print_Num, then use
-   --  C function print_num for the implementation.
-   procedure Print_Num (Num : Integer);
-   pragma Import (C, Print_Num, "print_num");
-
-begin
-   Print_Num (Get_Num);
-end My_Main;
-@end example
-
-To build this example:
-
-
-@itemize *
-
-@item 
-First compile the foreign language files to
-generate object files:
-
-@example
-$ gcc -c file1.c
-$ gcc -c file2.c
-@end example
-
-@item 
-Then, compile the Ada units to produce a set of object files and ALI
-files:
-
-@example
-$ gnatmake -c my_main.adb
-@end example
-
-@item 
-Run the Ada binder on the Ada main program:
-
-@example
-$ gnatbind my_main.ali
-@end example
-
-@item 
-Link the Ada main program, the Ada objects and the other language
-objects:
-
-@example
-$ gnatlink my_main.ali file1.o file2.o
-@end example
-@end itemize
-
-The last three steps can be grouped in a single command:
-
-@example
-$ gnatmake my_main.adb -largs file1.o file2.o
-@end example
-
-@geindex Binder output file
-
-If the main program is in a language other than Ada, then you may have
-more than one entry point into the Ada subsystem. You must use a special
-binder option to generate callable routines that initialize and
-finalize the Ada units (@ref{a0,,Binding with Non-Ada Main Programs}).
-Calls to the initialization and finalization routines must be inserted
-in the main program, or some other appropriate point in the code. The
-call to initialize the Ada units must occur before the first Ada
-subprogram is called, and the call to finalize the Ada units must occur
-after the last Ada subprogram returns. The binder will place the
-initialization and finalization subprograms into the
-@code{b~xxx.adb} file where they can be accessed by your C
-sources.  To illustrate, we have the following example:
-
-@example
-/* main.c */
-extern void adainit (void);
-extern void adafinal (void);
-extern int add (int, int);
-extern int sub (int, int);
-
-int main (int argc, char *argv[])
-@{
-   int a = 21, b = 7;
-
-   adainit();
-
-   /* Should print "21 + 7 = 28" */
-   printf ("%d + %d = %d\\n", a, b, add (a, b));
-
-   /* Should print "21 - 7 = 14" */
-   printf ("%d - %d = %d\\n", a, b, sub (a, b));
-
-   adafinal();
-@}
-@end example
-
-@example
---  unit1.ads
-package Unit1 is
-   function Add (A, B : Integer) return Integer;
-   pragma Export (C, Add, "add");
-end Unit1;
-@end example
-
-@example
---  unit1.adb
-package body Unit1 is
-   function Add (A, B : Integer) return Integer is
-   begin
-      return A + B;
-   end Add;
-end Unit1;
-@end example
-
-@example
---  unit2.ads
-package Unit2 is
-   function Sub (A, B : Integer) return Integer;
-   pragma Export (C, Sub, "sub");
-end Unit2;
-@end example
-
-@example
---  unit2.adb
-package body Unit2 is
-   function Sub (A, B : Integer) return Integer is
-   begin
-      return A - B;
-   end Sub;
-end Unit2;
-@end example
-
-The build procedure for this application is similar to the last
-example’s:
-
-
-@itemize *
-
-@item 
-First, compile the foreign language files to generate object files:
-
-@example
-$ gcc -c main.c
-@end example
-
-@item 
-Next, compile the Ada units to produce a set of object files and ALI
-files:
-
-@example
-$ gnatmake -c unit1.adb
-$ gnatmake -c unit2.adb
-@end example
-
-@item 
-Run the Ada binder on every generated ALI file.  Make sure to use the
-@code{-n} option to specify a foreign main program:
-
-@example
-$ gnatbind -n unit1.ali unit2.ali
-@end example
-
-@item 
-Link the Ada main program, the Ada objects and the foreign language
-objects. You need only list the last ALI file here:
-
-@example
-$ gnatlink unit2.ali main.o -o exec_file
-@end example
-
-This procedure yields a binary executable called @code{exec_file}.
-@end itemize
-
-Depending on the circumstances (for example when your non-Ada main object
-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 @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{a1}@anchor{gnat_ugn/the_gnat_compilation_model id63}@anchor{a2}
-@subsection Calling Conventions
-
-
-@geindex Foreign Languages
-
-@geindex Calling Conventions
-
-GNAT follows standard calling sequence conventions and will thus interface
-to any other language that also follows these conventions. The following
-Convention identifiers are recognized by GNAT:
-
-@geindex Interfacing to Ada
-
-@geindex Other Ada compilers
-
-@geindex Convention Ada
-
-
-@table @asis
-
-@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
-case where GNAT is used to generate both the caller and callee. It is also
-possible to mix GNAT generated code and code generated by another Ada
-compiler. In this case, the data types should be restricted to simple
-cases, including primitive types. Whether complex data types can be passed
-depends on the situation. Probably it is safe to pass simple arrays, such
-as arrays of integers or floats. Records may or may not work, depending
-on whether both compilers lay them out identically. Complex structures
-involving variant records, access parameters, tasks, or protected types,
-are unlikely to be able to be passed.
-
-Note that in the case of GNAT running
-on a platform that supports HP Ada 83, a higher degree of compatibility
-can be guaranteed, and in particular records are laid out in an identical
-manner in the two compilers. Note also that if output from two different
-compilers is mixed, the program is responsible for dealing with elaboration
-issues. Probably the safest approach is to write the main program in the
-version of Ada other than GNAT, so that it takes care of its own elaboration
-requirements, and then call the GNAT-generated adainit procedure to ensure
-elaboration of the GNAT components. Consult the documentation of the other
-Ada compiler for further details on elaboration.
-
-However, it is not possible to mix the tasking run time of GNAT and
-HP Ada 83, All the tasking operations must either be entirely within
-GNAT compiled sections of the program, or entirely within HP Ada 83
-compiled sections of the program.
-@end table
-
-@geindex Interfacing to Assembly
-
-@geindex Convention Assembler
-
-
-@table @asis
-
-@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
-considered the same convention).
-@end table
-
-@geindex Convention Asm
-
-@geindex Asm
-
-
-@table @asis
-
-@item @code{Asm}
-
-Equivalent to Assembler.
-
-@geindex Interfacing to COBOL
-
-@geindex Convention COBOL
-@end table
-
-@geindex COBOL
-
-
-@table @asis
-
-@item @code{COBOL}
-
-Data will be passed according to the conventions described
-in section B.4 of the Ada Reference Manual.
-@end table
-
-@geindex C
-
-@geindex Interfacing to C
-
-@geindex Convention C
-
-
-@table @asis
-
-@item @code{C}
-
-Data will be passed according to the conventions described
-in section B.3 of the Ada Reference Manual.
-
-A note on interfacing to a C ‘varargs’ function:
-
-@quotation
-
-@geindex C varargs function
-
-@geindex Interfacing to C varargs function
-
-@geindex varargs function interfaces
-
-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 @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 @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 @code{varargs} C function with
-the same two arguments.
-@end quotation
-@end table
-
-@geindex Convention Default
-
-@geindex Default
-
-
-@table @asis
-
-@item @code{Default}
-
-Equivalent to C.
-@end table
-
-@geindex Convention External
-
-@geindex External
-
-
-@table @asis
-
-@item @code{External}
-
-Equivalent to C.
-@end table
-
-@geindex C++
-
-@geindex Interfacing to C++
-
-@geindex Convention C++
-
-
-@table @asis
-
-@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
-C++ interfacing for further details.
-@end table
-
-@geindex Fortran
-
-@geindex Interfacing to Fortran
-
-@geindex Convention Fortran
-
-
-@table @asis
-
-@item @code{Fortran}
-
-Data will be passed according to the conventions described
-in section B.5 of the Ada Reference Manual.
-
-@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,
-this means that the body of the subprogram is provided by the compiler itself,
-usually by means of an efficient code sequence, and that the user does not
-supply an explicit body for it. In an application program, the pragma may
-be applied to the following sets of names:
-
-
-@itemize *
-
-@item 
-Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, Shift_Right_Arithmetic.
-The corresponding subprogram declaration must have
-two formal parameters. The
-first one must be a signed integer type or a modular type with a binary
-modulus, and the second parameter must be of type Natural.
-The return type must be the same as the type of the first argument. The size
-of this type can only be 8, 16, 32, or 64.
-
-@item 
-Binary arithmetic operators: ‘+’, ‘-’, ‘*’, ‘/’.
-The corresponding operator declaration must have parameters and result type
-that have the same root numeric type (for example, all three are long_float
-types). This simplifies the definition of operations that use type checking
-to perform dimensional checks:
-@end itemize
-
-@example
-  type Distance is new Long_Float;
-  type Time     is new Long_Float;
-  type Velocity is new Long_Float;
-  function "/" (D : Distance; T : Time)
-    return Velocity;
-  pragma Import (Intrinsic, "/");
-
-This common idiom is often programmed with a generic definition and an
-explicit body. The pragma makes it simpler to introduce such declarations.
-It incurs no overhead in compilation time or code size, because it is
-implemented as a single machine instruction.
-@end example
-
-
-@itemize *
-
-@item 
-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 @code{__builtin} functions
-exposed by the GCC back-end, as in the following example:
-
-@example
-function builtin_sqrt (F : Float) return Float;
-pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf");
-@end example
-
-Most of the GCC builtins are accessible this way, and as for other
-import conventions (e.g. C), it is the user’s responsibility to ensure
-that the Ada subprogram profile matches the underlying builtin
-expectations.
-@end itemize
-@end table
-
-@geindex Stdcall
-
-@geindex Convention Stdcall
-
-
-@table @asis
-
-@item @code{Stdcall}
-
-This is relevant only to Windows implementations of GNAT,
-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 @code{C} calling
-convention on non-Windows platforms.
-@end table
-
-@geindex DLL
-
-@geindex Convention DLL
-
-
-@table @asis
-
-@item @code{DLL}
-
-This is equivalent to @code{Stdcall}.
-@end table
-
-@geindex Win32
-
-@geindex Convention Win32
-
-
-@table @asis
-
-@item @code{Win32}
-
-This is equivalent to @code{Stdcall}.
-@end table
-
-@geindex Stubbed
-
-@geindex Convention Stubbed
-
-
-@table @asis
-
-@item @code{Stubbed}
-
-This is a special convention that indicates that the compiler
-should provide a stub body that raises @code{Program_Error}.
-@end table
-
-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
-pragma:
-
-@example
-pragma Convention_Identifier (Fortran77, Fortran);
-@end example
-
-And from now on the identifier Fortran77 may be used as a convention
-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
-@anchor{gnat_ugn/the_gnat_compilation_model building-mixed-ada-and-c-programs}@anchor{a3}@anchor{gnat_ugn/the_gnat_compilation_model id64}@anchor{a4}
-@subsection Building Mixed Ada and C++ Programs
-
-
-A programmer inexperienced with mixed-language development may find that
-building an application containing both Ada and C++ code can be a
-challenge.  This section gives a few hints that should make this task easier.
-
-@menu
-* Interfacing to C++:: 
-* Linking a Mixed C++ & Ada Program:: 
-* A Simple Example:: 
-* Interfacing with C++ constructors:: 
-* Interfacing with C++ at the Class Level:: 
-
-@end menu
-
-@node Interfacing to C++,Linking a Mixed C++ & Ada Program,,Building Mixed Ada and C++ Programs
-@anchor{gnat_ugn/the_gnat_compilation_model id65}@anchor{a5}@anchor{gnat_ugn/the_gnat_compilation_model id66}@anchor{a6}
-@subsubsection Interfacing to C++
-
-
-GNAT supports interfacing with the G++ compiler (or any C++ compiler
-generating code that is compatible with the G++ Application Binary
-Interface —see @indicateurl{http://itanium-cxx-abi.github.io/cxx-abi/abi.html}).
-
-Interfacing can be done at 3 levels: simple data, subprograms, and
-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{a7,,Generating Ada Bindings for C and C++ headers}).
-This problem can also be addressed manually in two ways:
-
-
-@itemize *
-
-@item 
-by modifying the C++ code in order to force a C convention using
-the @code{extern "C"} syntax.
-
-@item 
-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 @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{a8}@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-and-ada-program}@anchor{a9}
-@subsubsection Linking a Mixed C++ & Ada Program
-
-
-Usually the linker of the C++ development system must be used to link
-mixed applications because most C++ systems will resolve elaboration
-issues (such as calling constructors on global class instances)
-transparently during the link phase. GNAT has been adapted to ease the
-use of a foreign linker for the last phase. Three cases can be
-considered:
-
-
-@itemize *
-
-@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 @code{g++}.
-
-Note that if the C++ code uses inline functions, you will need to
-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.
-
-@example
-$ g++ -c -fkeep-inline-functions file1.C
-$ g++ -c -fkeep-inline-functions file2.C
-$ gnatmake ada_unit -largs file1.o file2.o --LINK=g++
-@end example
-
-@item 
-Using GNAT and G++ from two different GCC installations: If both
-compilers are on the :envvar`PATH`, the previous method may be used. It is
-important to note that environment variables such as
-@geindex C_INCLUDE_PATH
-@geindex environment variable; C_INCLUDE_PATH
-@code{C_INCLUDE_PATH}, 
-@geindex GCC_EXEC_PREFIX
-@geindex environment variable; GCC_EXEC_PREFIX
-@code{GCC_EXEC_PREFIX},
-@geindex BINUTILS_ROOT
-@geindex environment variable; BINUTILS_ROOT
-@code{BINUTILS_ROOT}, and
-@geindex GCC_ROOT
-@geindex environment variable; GCC_ROOT
-@code{GCC_ROOT} will affect both compilers
-at the same time and may make one of the two compilers operate
-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 @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:
-
-@example
-$ gnatbind ada_unit
-$ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++
-@end example
-
-If there is a problem due to interfering environment variables, it can
-be worked around by using an intermediate script. The following example
-shows the proper script to use when GNAT has not been installed at its
-default location and g++ has been installed at its default location:
-
-@example
-$ cat ./my_script
-#!/bin/sh
-unset BINUTILS_ROOT
-unset GCC_ROOT
-c++ $*
-$ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script
-@end example
-
-@item 
-Using a non-GNU C++ compiler: The commands previously described can be
-used to insure that the C++ linker is used. Nonetheless, you need to add
-a few more parameters to the link command line, depending on the exception
-mechanism used.
-
-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
-$ 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 “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
-$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
-@end example
-
-If the “zero cost exception” mechanism is used, and the platform
-doesn’t support automatic registration of exception tables (e.g., HP-UX
-or AIX), the simple approach described above will not work and
-a pre-linking phase using GNAT will be necessary.
-@end itemize
-
-Another alternative is to use the @code{gprbuild} multi-language builder
-which has a large knowledge base and knows how to link Ada and C++ code
-together automatically in most cases.
-
-@node A Simple Example,Interfacing with C++ constructors,Linking a Mixed C++ & Ada Program,Building Mixed Ada and C++ Programs
-@anchor{gnat_ugn/the_gnat_compilation_model a-simple-example}@anchor{aa}@anchor{gnat_ugn/the_gnat_compilation_model id67}@anchor{ab}
-@subsubsection A Simple Example
-
-
-The following example, provided as part of the GNAT examples, shows how
-to achieve procedural interfacing between Ada and C++ in both
-directions. The C++ class A has two methods. The first method is exported
-to Ada by the means of an extern C wrapper function. The second method
-calls an Ada subprogram. On the Ada side, the C++ calls are modelled by
-a limited record with a layout comparable to the C++ class. The Ada
-subprogram, in turn, calls the C++ method. So, starting from the C++
-main program, the process passes back and forth between the two
-languages.
-
-Here are the compilation commands:
-
-@example
-$ gnatmake -c simple_cpp_interface
-$ g++ -c cpp_main.C
-$ g++ -c ex7.C
-$ gnatbind -n simple_cpp_interface
-$ gnatlink simple_cpp_interface -o cpp_main --LINK=g++ -lstdc++ ex7.o cpp_main.o
-@end example
-
-Here are the corresponding sources:
-
-@example
-//cpp_main.C
-
-#include "ex7.h"
-
-extern "C" @{
-  void adainit (void);
-  void adafinal (void);
-  void method1 (A *t);
-@}
-
-void method1 (A *t)
-@{
-  t->method1 ();
-@}
-
-int main ()
-@{
-  A obj;
-  adainit ();
-  obj.method2 (3030);
-  adafinal ();
-@}
-@end example
-
-@example
-//ex7.h
-
-class Origin @{
- public:
-  int o_value;
-@};
-class A : public Origin @{
- public:
-  void method1 (void);
-  void method2 (int v);
-  A();
-  int   a_value;
-@};
-@end example
-
-@example
-//ex7.C
-
-#include "ex7.h"
-#include <stdio.h>
-
-extern "C" @{ void ada_method2 (A *t, int v);@}
-
-void A::method1 (void)
-@{
-  a_value = 2020;
-  printf ("in A::method1, a_value = %d \\n",a_value);
-@}
-
-void A::method2 (int v)
-@{
-   ada_method2 (this, v);
-   printf ("in A::method2, a_value = %d \\n",a_value);
-@}
-
-A::A(void)
-@{
-   a_value = 1010;
-  printf ("in A::A, a_value = %d \\n",a_value);
-@}
-@end example
-
-@example
--- simple_cpp_interface.ads
-with System;
-package Simple_Cpp_Interface is
-   type A is limited
-      record
-         Vptr    : System.Address;
-         O_Value : Integer;
-         A_Value : Integer;
-      end record;
-   pragma Convention (C, A);
-
-   procedure Method1 (This : in out A);
-   pragma Import (C, Method1);
-
-   procedure Ada_Method2 (This : in out A; V : Integer);
-   pragma Export (C, Ada_Method2);
-
-end Simple_Cpp_Interface;
-@end example
-
-@example
--- simple_cpp_interface.adb
-package body Simple_Cpp_Interface is
-
-   procedure Ada_Method2 (This : in out A; V : Integer) is
-   begin
-      Method1 (This);
-      This.A_Value := V;
-   end Ada_Method2;
-
-end Simple_Cpp_Interface;
-@end example
-
-@node Interfacing with C++ constructors,Interfacing with C++ at the Class Level,A Simple Example,Building Mixed Ada and C++ Programs
-@anchor{gnat_ugn/the_gnat_compilation_model id68}@anchor{ac}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-constructors}@anchor{ad}
-@subsubsection Interfacing with C++ constructors
-
-
-In order to interface with C++ constructors GNAT provides the
-@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.
-
-Let us assume that we need to interface with the following
-C++ class:
-
-@example
-class Root @{
-public:
-  int  a_value;
-  int  b_value;
-  virtual int Get_Value ();
-  Root();              // Default constructor
-  Root(int v);         // 1st non-default constructor
-  Root(int v, int w);  // 2nd non-default constructor
-@};
-@end example
-
-For this purpose we can write the following package spec (further
-information on how to build this spec is available in
-@ref{ae,,Interfacing with C++ at the Class Level} and
-@ref{a7,,Generating Ada Bindings for C and C++ headers}).
-
-@example
-with Interfaces.C; use Interfaces.C;
-package Pkg_Root is
-  type Root is tagged limited record
-     A_Value : int;
-     B_Value : int;
-  end record;
-  pragma Import (CPP, Root);
-
-  function Get_Value (Obj : Root) return int;
-  pragma Import (CPP, Get_Value);
-
-  function Constructor return Root;
-  pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev");
-
-  function Constructor (v : Integer) return Root;
-  pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei");
-
-  function Constructor (v, w : Integer) return Root;
-  pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii");
-end Pkg_Root;
-@end example
-
-On the Ada side the constructor is represented by a function (whose
-name is arbitrary) that returns the classwide type corresponding to
-the imported C++ class. Although the constructor is described as a
-function, it is typically a procedure with an extra implicit argument
-(the object being initialized) at the implementation level. GNAT
-issues the appropriate call, whatever it is, to get the object
-properly initialized.
-
-Constructors can only appear in the following contexts:
-
-
-@itemize *
-
-@item 
-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 @code{T}.
-
-@item 
-In an Ada 2005 limited aggregate.
-
-@item 
-In an Ada 2005 nested limited aggregate.
-
-@item 
-In an Ada 2005 limited aggregate that initializes an object built in
-place by an extended return statement.
-@end itemize
-
-In a declaration of an object whose type is a class imported from C++,
-either the default C++ constructor is implicitly called by GNAT, or
-else the required C++ constructor must be explicitly called in the
-expression that initializes the object. For example:
-
-@example
-Obj1 : Root;
-Obj2 : Root := Constructor;
-Obj3 : Root := Constructor (v => 10);
-Obj4 : Root := Constructor (30, 40);
-@end example
-
-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). @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:
-
-@example
-type DT is new Root with record
-   C_Value : Natural := 2009;
-end record;
-@end example
-
-In this case the components DT inherited from the C++ side must be
-initialized by a C++ constructor, and the additional Ada components
-of type DT are initialized by GNAT. The initialization of such an
-object is done either by default, or by means of a function returning
-an aggregate of type DT, or by means of an extension aggregate.
-
-@example
-Obj5 : DT;
-Obj6 : DT := Function_Returning_DT (50);
-Obj7 : DT := (Constructor (30,40) with C_Value => 50);
-@end example
-
-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,
-@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.
-
-Let us now consider a record that has components whose type is imported
-from C++. For example:
-
-@example
-type Rec1 is limited record
-   Data1 : Root := Constructor (10);
-   Value : Natural := 1000;
-end record;
-
-type Rec2 (D : Integer := 20) is limited record
-   Rec   : Rec1;
-   Data2 : Root := Constructor (D, 30);
-end record;
-@end example
-
-The initialization of an object of type @code{Rec2} will call the
-non-default C++ constructors specified for the imported components.
-For example:
-
-@example
-Obj8 : Rec2 (40);
-@end example
-
-Using Ada 2005 we can use limited aggregates to initialize an object
-invoking C++ constructors that differ from those specified in the type
-declarations. For example:
-
-@example
-Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16),
-                        others => <>),
-                others => <>);
-@end example
-
-The above declaration uses an Ada 2005 limited aggregate to
-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 @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 @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:
-
-@example
-function Constructor (V : Integer) return Rec2 is
-begin
-   return Obj : Rec2 := (Rec => (Data1  => Constructor (V, 20),
-                                 others => <>),
-                         others => <>) do
-      --  Further actions required for construction of
-      --  objects of type Rec2
-      ...
-   end record;
-end Constructor;
-@end example
-
-In this example the extended return statement construct is used to
-build in place the returned object whose components are initialized
-by means of a limited aggregate. Any further action associated with
-the constructor can be placed inside the construct.
-
-@node Interfacing with C++ at the Class Level,,Interfacing with C++ constructors,Building Mixed Ada and C++ Programs
-@anchor{gnat_ugn/the_gnat_compilation_model id69}@anchor{af}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-at-the-class-level}@anchor{ae}
-@subsubsection Interfacing with C++ at the Class Level
-
-
-In this section we demonstrate the GNAT features for interfacing with
-C++ by means of an example making use of Ada 2005 abstract interface
-types. This example consists of a classification of animals; classes
-have been used to model our main classification of animals, and
-interfaces provide support for the management of secondary
-classifications. We first demonstrate a case in which the types and
-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 @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
-class Animal @{
- public:
-   virtual void Set_Age (int New_Age);
-   virtual int Age ();
-   Animal() @{Age_Count = 0;@};
- private:
-   int Age_Count;
-@};
-@end 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 @code{Carnivore}
-and @code{Domestic} animals:
-
-@example
-class Carnivore @{
-public:
-   virtual int Number_Of_Teeth () = 0;
-@};
-
-class Domestic @{
-public:
-   virtual void Set_Owner (char* Name) = 0;
-@};
-@end example
-
-Using these declarations, we can now say that a @code{Dog} is an animal that is
-both Carnivore and Domestic, that is:
-
-@example
-class Dog : Animal, Carnivore, Domestic @{
- public:
-   virtual int  Number_Of_Teeth ();
-   virtual void Set_Owner (char* Name);
-
-   Dog(); // Constructor
- private:
-   int  Tooth_Count;
-   char *Owner;
-@};
-@end example
-
-In the following examples we will assume that the previous declarations are
-located in a file named @code{animals.h}. The following package demonstrates
-how to import these C++ declarations from the Ada side:
-
-@example
-with Interfaces.C.Strings; use Interfaces.C.Strings;
-package Animals is
-  type Carnivore is limited interface;
-  pragma Convention (C_Plus_Plus, Carnivore);
-  function Number_Of_Teeth (X : Carnivore)
-     return Natural is abstract;
-
-  type Domestic is limited interface;
-  pragma Convention (C_Plus_Plus, Domestic);
-  procedure Set_Owner
-    (X    : in out Domestic;
-     Name : Chars_Ptr) is abstract;
-
-  type Animal is tagged limited record
-    Age : Natural;
-  end record;
-  pragma Import (C_Plus_Plus, Animal);
-
-  procedure Set_Age (X : in out Animal; Age : Integer);
-  pragma Import (C_Plus_Plus, Set_Age);
-
-  function Age (X : Animal) return Integer;
-  pragma Import (C_Plus_Plus, Age);
-
-  function New_Animal return Animal;
-  pragma CPP_Constructor (New_Animal);
-  pragma Import (CPP, New_Animal, "_ZN6AnimalC1Ev");
-
-  type Dog is new Animal and Carnivore and Domestic with record
-    Tooth_Count : Natural;
-    Owner       : Chars_Ptr;
-  end record;
-  pragma Import (C_Plus_Plus, Dog);
-
-  function Number_Of_Teeth (A : Dog) return Natural;
-  pragma Import (C_Plus_Plus, Number_Of_Teeth);
-
-  procedure Set_Owner (A : in out Dog; Name : Chars_Ptr);
-  pragma Import (C_Plus_Plus, Set_Owner);
-
-  function New_Dog return Dog;
-  pragma CPP_Constructor (New_Dog);
-  pragma Import (CPP, New_Dog, "_ZN3DogC2Ev");
-end Animals;
-@end example
-
-Thanks to the compatibility between GNAT run-time structures and the C++ ABI,
-interfacing with these C++ classes is easy. The only requirement is that all
-the primitives and components must be declared exactly in the same order in
-the two languages.
-
-Regarding the abstract interfaces, we must indicate to the GNAT compiler by
-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 @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
-which Ada would otherwise expect.
-
-As the reader can see there is no need to indicate the C++ mangled names
-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
-@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
-and dispatch calls to the corresponding subprograms on the C++ side. We can
-also extend the tagged type Dog with further fields and primitives, and
-override some of its C++ primitives on the Ada side. For example, here we have
-a type derivation defined on the Ada side that inherits all the dispatching
-primitives of the ancestor from the C++ side.
-
-@example
-with Animals; use Animals;
-package Vaccinated_Animals is
-  type Vaccinated_Dog is new Dog with null record;
-  function Vaccination_Expired (A : Vaccinated_Dog) return Boolean;
-end Vaccinated_Animals;
-@end example
-
-It is important to note that, because of the ABI compatibility, the programmer
-does not need to add any further information to indicate either the object
-layout or the dispatch table entry associated with each dispatching operation.
-
-Now let us define all the types and constructors on the Ada side and export
-them to C++, using the same hierarchy of our previous example:
-
-@example
-with Interfaces.C.Strings;
-use Interfaces.C.Strings;
-package Animals is
-  type Carnivore is limited interface;
-  pragma Convention (C_Plus_Plus, Carnivore);
-  function Number_Of_Teeth (X : Carnivore)
-     return Natural is abstract;
-
-  type Domestic is limited interface;
-  pragma Convention (C_Plus_Plus, Domestic);
-  procedure Set_Owner
-    (X    : in out Domestic;
-     Name : Chars_Ptr) is abstract;
-
-  type Animal is tagged record
-    Age : Natural;
-  end record;
-  pragma Convention (C_Plus_Plus, Animal);
-
-  procedure Set_Age (X : in out Animal; Age : Integer);
-  pragma Export (C_Plus_Plus, Set_Age);
-
-  function Age (X : Animal) return Integer;
-  pragma Export (C_Plus_Plus, Age);
-
-  function New_Animal return Animal'Class;
-  pragma Export (C_Plus_Plus, New_Animal);
-
-  type Dog is new Animal and Carnivore and Domestic with record
-    Tooth_Count : Natural;
-    Owner       : String (1 .. 30);
-  end record;
-  pragma Convention (C_Plus_Plus, Dog);
-
-  function Number_Of_Teeth (A : Dog) return Natural;
-  pragma Export (C_Plus_Plus, Number_Of_Teeth);
-
-  procedure Set_Owner (A : in out Dog; Name : Chars_Ptr);
-  pragma Export (C_Plus_Plus, Set_Owner);
-
-  function New_Dog return Dog'Class;
-  pragma Export (C_Plus_Plus, New_Dog);
-end Animals;
-@end example
-
-Compared with our previous example the only differences are the use of
-@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 @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:
-
-@example
-#include "animals.h"
-#include <iostream>
-using namespace std;
-
-void Check_Carnivore (Carnivore *obj) @{...@}
-void Check_Domestic (Domestic *obj)   @{...@}
-void Check_Animal (Animal *obj)       @{...@}
-void Check_Dog (Dog *obj)             @{...@}
-
-extern "C" @{
-  void adainit (void);
-  void adafinal (void);
-  Dog* new_dog ();
-@}
-
-void test ()
-@{
-  Dog *obj = new_dog();  // Ada constructor
-  Check_Carnivore (obj); // Check secondary DT
-  Check_Domestic (obj);  // Check secondary DT
-  Check_Animal (obj);    // Check primary DT
-  Check_Dog (obj);       // Check primary DT
-@}
-
-int main ()
-@{
-  adainit ();  test();  adafinal ();
-  return 0;
-@}
-@end example
-
-@node Generating Ada Bindings for C and C++ headers,Generating C Headers for Ada Specifications,Building Mixed Ada and C++ Programs,Mixed Language Programming
-@anchor{gnat_ugn/the_gnat_compilation_model generating-ada-bindings-for-c-and-c-headers}@anchor{a7}@anchor{gnat_ugn/the_gnat_compilation_model id70}@anchor{b0}
-@subsection Generating Ada Bindings for C and C++ headers
-
-
-@geindex Binding generation (for C and C++ headers)
-
-@geindex C headers (binding generation)
-
-@geindex C++ headers (binding generation)
-
-GNAT includes a binding generator for C and C++ headers which is
-intended to do 95% of the tedious work of generating Ada specs from C
-or C++ header files.
-
-Note that this capability is not intended to generate 100% correct Ada specs,
-and will is some cases require manual adjustments, although it can often
-be used out of the box in practice.
-
-Some of the known limitations include:
-
-
-@itemize *
-
-@item 
-only very simple character constant macros are translated into Ada
-constants. Function macros (macros with arguments) are partially translated
-as comments, to be completed manually if needed.
-
-@item 
-some extensions (e.g. vector types) are not supported
-
-@item 
-pointers to pointers are mapped to System.Address
-
-@item 
-identifiers with identical name (except casing) may generate compilation
-errors (e.g. @code{shm_get} vs @code{SHM_GET}).
-@end itemize
-
-The code is generated using Ada 2012 syntax, which makes it easier to interface
-with other languages. In most cases you can still use the generated binding
-even if your code is compiled using earlier versions of Ada (e.g. @code{-gnat95}).
-
-@menu
-* Running the Binding Generator:: 
-* Generating Bindings for C++ Headers:: 
-* Switches:: 
-
-@end menu
-
-@node Running the Binding Generator,Generating Bindings for C++ Headers,,Generating Ada Bindings for C and C++ headers
-@anchor{gnat_ugn/the_gnat_compilation_model id71}@anchor{b1}@anchor{gnat_ugn/the_gnat_compilation_model running-the-binding-generator}@anchor{b2}
-@subsubsection Running the Binding Generator
-
-
-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:
-
-@example
-$ gcc -c -fdump-ada-spec -C /usr/include/time.h
-$ gcc -c *.ads
-@end 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 then compile these Ada specs.
-That is to say, the name of the Ada specs is in keeping with the relative path
-under @code{/usr/include/} of the header files. This behavior is specific to
-paths ending with @code{/include/}; in all the other cases, the name of the
-Ada specs is derived from the simple name of the header files instead.
-
-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 @code{-fdump-ada-spec-slim} switch.
-
-You can optionally specify a parent unit, of which all generated units will
-be children, using @code{-fada-spec-parent=`unit'}.
-
-The simple @code{gcc}-based command works only for C headers. For C++ headers
-you need to use either the @code{g++} command or the combination @code{gcc -x c++}.
-
-In some cases, the generated bindings will be more complete or more meaningful
-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
-$ gcc -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h
-@end example
-
-The above will generate more complete bindings than a straight call without
-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
-@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}:
-
-@example
-#include <stdio.h>
-#include <readline/readline.h>
-@end example
-
-and then generate Ada bindings from this file:
-
-@example
-$ gcc -c -fdump-ada-spec readline1.h
-@end example
-
-@node Generating Bindings for C++ Headers,Switches,Running the Binding Generator,Generating Ada Bindings for C and C++ headers
-@anchor{gnat_ugn/the_gnat_compilation_model generating-bindings-for-c-headers}@anchor{b3}@anchor{gnat_ugn/the_gnat_compilation_model id72}@anchor{b4}
-@subsubsection Generating Bindings for C++ Headers
-
-
-Generating bindings for C++ headers is done using the same options, always
-with the `g++' compiler. Note that generating Ada spec from C++ headers is a
-much more complex job and support for C++ headers is much more limited that
-support for C headers. As a result, you will need to modify the resulting
-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 @code{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 @cite{GNAT Reference Manual}
-for additional information on interfacing to C++).
-
-For example, given the following C++ header file:
-
-@example
-class Carnivore @{
-public:
-   virtual int Number_Of_Teeth () = 0;
-@};
-
-class Domestic @{
-public:
-   virtual void Set_Owner (char* Name) = 0;
-@};
-
-class Animal @{
-public:
-  int Age_Count;
-  virtual void Set_Age (int New_Age);
-@};
-
-class Dog : Animal, Carnivore, Domestic @{
- public:
-  int  Tooth_Count;
-  char *Owner;
-
-  virtual int  Number_Of_Teeth ();
-  virtual void Set_Owner (char* Name);
-
-  Dog();
-@};
-@end example
-
-The corresponding Ada code is generated:
-
-@example
-package Class_Carnivore is
-  type Carnivore is limited interface;
-  pragma Import (CPP, Carnivore);
-
-  function Number_Of_Teeth (this : access Carnivore) return int is abstract;
-end;
-use Class_Carnivore;
-
-package Class_Domestic is
-  type Domestic is limited interface;
-  pragma Import (CPP, Domestic);
-
-  procedure Set_Owner
-    (this : access Domestic;
-     Name : Interfaces.C.Strings.chars_ptr) is abstract;
-end;
-use Class_Domestic;
-
-package Class_Animal is
-  type Animal is tagged limited record
-    Age_Count : aliased int;
-  end record;
-  pragma Import (CPP, Animal);
-
-  procedure Set_Age (this : access Animal; New_Age : int);
-  pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi");
-end;
-use Class_Animal;
-
-package Class_Dog is
-  type Dog is new Animal and Carnivore and Domestic with record
-    Tooth_Count : aliased int;
-    Owner : Interfaces.C.Strings.chars_ptr;
-  end record;
-  pragma Import (CPP, Dog);
-
-  function Number_Of_Teeth (this : access Dog) return int;
-  pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv");
-
-  procedure Set_Owner
-    (this : access Dog; Name : Interfaces.C.Strings.chars_ptr);
-  pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc");
-
-  function New_Dog return Dog;
-  pragma CPP_Constructor (New_Dog);
-  pragma Import (CPP, New_Dog, "_ZN3DogC1Ev");
-end;
-use Class_Dog;
-@end example
-
-@node Switches,,Generating Bindings for C++ Headers,Generating Ada Bindings for C and C++ headers
-@anchor{gnat_ugn/the_gnat_compilation_model switches}@anchor{b5}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-ada-binding-generation}@anchor{b6}
-@subsubsection Switches
-
-
-@geindex -fdump-ada-spec (gcc)
-
-
-@table @asis
-
-@item @code{-fdump-ada-spec}
-
-Generate Ada spec files for the given header files transitively (including
-all header files that these headers depend upon).
-@end table
-
-@geindex -fdump-ada-spec-slim (gcc)
-
-
-@table @asis
-
-@item @code{-fdump-ada-spec-slim}
-
-Generate Ada spec files for the header files specified on the command line
-only.
-@end table
-
-@geindex -fada-spec-parent (gcc)
-
-
-@table @asis
-
-@item @code{-fada-spec-parent=`unit'}
-
-Specifies that all files generated by @code{-fdump-ada-spec} are
-to be child units of the specified parent unit.
-@end table
-
-@geindex -C (gcc)
-
-
-@table @asis
-
-@item @code{-C}
-
-Extract comments from headers and generate Ada comments in the Ada spec files.
-@end table
-
-@node Generating C Headers for Ada Specifications,,Generating Ada Bindings for C and C++ headers,Mixed Language Programming
-@anchor{gnat_ugn/the_gnat_compilation_model generating-c-headers-for-ada-specifications}@anchor{b7}@anchor{gnat_ugn/the_gnat_compilation_model id73}@anchor{b8}
-@subsection Generating C Headers for Ada Specifications
-
-
-@geindex Binding generation (for Ada specs)
-
-@geindex C headers (binding generation)
-
-GNAT includes a C header generator for Ada specifications which supports
-Ada types that have a direct mapping to C types. This includes in particular
-support for:
-
-
-@itemize *
-
-@item 
-Scalar types
-
-@item 
-Constrained arrays
-
-@item 
-Records (untagged)
-
-@item 
-Composition of the above types
-
-@item 
-Constant declarations
-
-@item 
-Object declarations
-
-@item 
-Subprogram declarations
-@end itemize
-
-@menu
-* Running the C Header Generator:: 
-
-@end menu
-
-@node Running the C Header Generator,,,Generating C Headers for Ada Specifications
-@anchor{gnat_ugn/the_gnat_compilation_model running-the-c-header-generator}@anchor{b9}
-@subsubsection Running the C Header Generator
-
-
-The C header generator is part of the GNAT compiler and can be invoked via
-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:
-
-@example
-$ gcc -c -gnatceg pack1.ads
-@end example
-
-will generate a self-contained file called @code{pack1.h} including
-common definitions from the Ada Standard package, followed by the
-definitions included in @code{pack1.ads}, as well as all the other units
-withed by this file.
-
-For instance, given the following Ada files:
-
-@example
-package Pack2 is
-   type Int is range 1 .. 10;
-end Pack2;
-@end example
-
-@example
-with Pack2;
-
-package Pack1 is
-   type Rec is record
-      Field1, Field2 : Pack2.Int;
-   end record;
-
-   Global : Rec := (1, 2);
-
-   procedure Proc1 (R : Rec);
-   procedure Proc2 (R : in out Rec);
-end Pack1;
-@end example
-
-The above @code{gcc} command will generate the following @code{pack1.h} file:
-
-@example
-/* Standard definitions skipped */
-#ifndef PACK2_ADS
-#define PACK2_ADS
-typedef short_short_integer pack2__TintB;
-typedef pack2__TintB pack2__int;
-#endif /* PACK2_ADS */
-
-#ifndef PACK1_ADS
-#define PACK1_ADS
-typedef struct _pack1__rec @{
-  pack2__int field1;
-  pack2__int field2;
-@} pack1__rec;
-extern pack1__rec pack1__global;
-extern void pack1__proc1(const pack1__rec r);
-extern void pack1__proc2(pack1__rec *r);
-#endif /* PACK1_ADS */
-@end example
-
-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
-@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-other-compilation-models}@anchor{2d}@anchor{gnat_ugn/the_gnat_compilation_model id74}@anchor{ba}
-@section GNAT and Other Compilation Models
-
-
-This section compares the GNAT model with the approaches taken in
-other environments, first the C/C++ model and then the mechanism that
-has been used in other Ada systems, in particular those traditionally
-used for Ada 83.
-
-@menu
-* Comparison between GNAT and C/C++ Compilation Models:: 
-* Comparison between GNAT and Conventional Ada Library Models:: 
-
-@end menu
-
-@node Comparison between GNAT and C/C++ Compilation Models,Comparison between GNAT and Conventional Ada Library Models,,GNAT and Other Compilation Models
-@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-c-c-compilation-models}@anchor{bb}@anchor{gnat_ugn/the_gnat_compilation_model id75}@anchor{bc}
-@subsection Comparison between GNAT and C/C++ 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 @code{#include} of a C
-header.
-
-One notable difference is that, in Ada, you may compile specs separately
-to check them for semantic and syntactic accuracy. This is not always
-possible with C headers because they are fragments of programs that have
-less specific syntactic or semantic rules.
-
-The other major difference is the requirement for running the binder,
-which performs two important functions. First, it checks for
-consistency. In C or C++, the only defense against assembling
-inconsistent programs lies outside the compiler, in a makefile, for
-example. The binder satisfies the Ada requirement that it be impossible
-to construct an inconsistent program when the compiler is used in normal
-mode.
-
-@geindex Elaboration order control
-
-The other important function of the binder is to deal with elaboration
-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 @code{gnatbind} might complain there was no valid order of
-elaboration, a C++ compiler would simply construct a program that
-malfunctioned at run time.
-
-@node Comparison between GNAT and Conventional Ada Library Models,,Comparison between GNAT and C/C++ Compilation Models,GNAT and Other Compilation Models
-@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-conventional-ada-library-models}@anchor{bd}@anchor{gnat_ugn/the_gnat_compilation_model id76}@anchor{be}
-@subsection Comparison between GNAT and Conventional Ada Library Models
-
-
-This section is intended for Ada programmers who have
-used an Ada compiler implementing the traditional Ada library
-model, as described in the Ada Reference Manual.
-
-@geindex GNAT library
-
-In GNAT, there is no ‘library’ in the normal sense. Instead, the set of
-source files themselves acts as the library. Compiling Ada programs does
-not generate any centralized information, but rather an object file and
-a ALI file, which are of interest only to the binder and linker.
-In a traditional system, the compiler reads information not only from
-the source file being compiled, but also from the centralized library.
-This means that the effect of a compilation depends on what has been
-previously compiled. In particular:
-
-
-@itemize *
-
-@item 
-When a unit is `with'ed, the unit seen by the compiler corresponds
-to the version of the unit most recently compiled into the library.
-
-@item 
-Inlining is effective only if the necessary body has already been
-compiled into the library.
-
-@item 
-Compiling a unit may obsolete other units in the library.
-@end itemize
-
-In GNAT, compiling one unit never affects the compilation of any other
-units because the compiler reads only source files. Only changes to source
-files can affect the results of a compilation. In particular:
-
-
-@itemize *
-
-@item 
-When a unit is `with'ed, the unit seen by the compiler corresponds
-to the source version of the unit that is currently accessible to the
-compiler.
-
-@geindex Inlining
-
-@item 
-Inlining requires the appropriate source files for the package or
-subprogram bodies to be available to the compiler. Inlining is always
-effective, independent of the order in which units are compiled.
-
-@item 
-Compiling a unit never affects any other compilations. The editing of
-sources may cause previous compilations to be out of date if they
-depended on the source file being modified.
-@end itemize
-
-The most important result of these differences is that order of compilation
-is never significant in GNAT. There is no situation in which one is
-required to do one compilation before another. What shows up as order of
-compilation requirements in the traditional Ada library becomes, in
-GNAT, simple source dependencies; in other words, there is only a set
-of rules saying what source files must be present when a file is
-compiled.
-
-@node Using GNAT Files with External Tools,,GNAT and Other Compilation Models,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id77}@anchor{bf}@anchor{gnat_ugn/the_gnat_compilation_model using-gnat-files-with-external-tools}@anchor{2e}
-@section Using GNAT Files with External Tools
-
-
-This section explains how files that are produced by GNAT may be
-used with tools designed for other languages.
-
-@menu
-* Using Other Utility Programs with GNAT:: 
-* The External Symbol Naming Scheme of GNAT:: 
-
-@end menu
-
-@node Using Other Utility Programs with GNAT,The External Symbol Naming Scheme of GNAT,,Using GNAT Files with External Tools
-@anchor{gnat_ugn/the_gnat_compilation_model id78}@anchor{c0}@anchor{gnat_ugn/the_gnat_compilation_model using-other-utility-programs-with-gnat}@anchor{c1}
-@subsection Using Other Utility Programs with GNAT
-
-
-The object files generated by GNAT are in standard system format and in
-particular the debugging information uses this format. This means
-programs generated by GNAT can be used with existing utilities that
-depend on these formats.
-
-In general, any utility program that works with C will also often work with
-Ada programs generated by GNAT. This includes software utilities such as
-gprof (a profiling program), gdb (the FSF debugger), and utilities such
-as Purify.
-
-@node The External Symbol Naming Scheme of GNAT,,Using Other Utility Programs with GNAT,Using GNAT Files with External Tools
-@anchor{gnat_ugn/the_gnat_compilation_model id79}@anchor{c2}@anchor{gnat_ugn/the_gnat_compilation_model the-external-symbol-naming-scheme-of-gnat}@anchor{c3}
-@subsection The External Symbol Naming Scheme of GNAT
-
-
-In order to interpret the output from GNAT, when using tools that are
-originally intended for use with other languages, it is useful to
-understand the conventions used to generate link names from the Ada
-entity names.
-
-All link names are in all lowercase letters. With the exception of library
-procedure names, the mechanism used is simply to use the full expanded
-Ada name with dots replaced by double underscores. For example, suppose
-we have the following package spec:
-
-@example
-package QRS is
-   MN : Integer;
-end QRS;
-@end example
-
-@geindex pragma Export
-
-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
-   Var1 : Integer;
-   pragma Export (Var1, C, External_Name => "var1_name");
-   Var2 : Integer;
-   pragma Export (Var2, C, Link_Name => "var2_link_name");
-end Exports;
-@end example
-
-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
-@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 @code{_main} for the C main program,
-and the name we would otherwise assign to an Ada library level procedure
-called @code{Main} (which might well not be the main program).
-
-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 @code{_ada_hello}.
-
-@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
-
-@node Building Executable Programs with GNAT,GNAT Utility Programs,The GNAT Compilation Model,Top
-@anchor{gnat_ugn/building_executable_programs_with_gnat doc}@anchor{c4}@anchor{gnat_ugn/building_executable_programs_with_gnat building-executable-programs-with-gnat}@anchor{a}@anchor{gnat_ugn/building_executable_programs_with_gnat id1}@anchor{c5}
-@chapter Building Executable Programs with GNAT
-
-
-This chapter describes first the gnatmake tool
-(@ref{c6,,Building with gnatmake}),
-which automatically determines the set of sources
-needed by an Ada compilation unit and executes the necessary
-(re)compilations, binding and linking.
-It also explains how to use each tool individually: the
-compiler (gcc, see @ref{c7,,Compiling with gcc}),
-binder (gnatbind, see @ref{c8,,Binding with gnatbind}),
-and linker (gnatlink, see @ref{c9,,Linking with gnatlink})
-to build executable programs.
-Finally, this chapter provides examples of
-how to make use of the general GNU make mechanism
-in a GNAT context (see @ref{70,,Using the GNU make Utility}).
-
-
-@menu
-* Building with gnatmake:: 
-* Compiling with gcc:: 
-* Compiler Switches:: 
-* Linker Switches:: 
-* Binding with gnatbind:: 
-* Linking with gnatlink:: 
-* Using the GNU make Utility:: 
-
-@end menu
-
-@node Building with gnatmake,Compiling with gcc,,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat building-with-gnatmake}@anchor{ca}@anchor{gnat_ugn/building_executable_programs_with_gnat the-gnat-make-program-gnatmake}@anchor{c6}
-@section Building with @code{gnatmake}
-
-
-@geindex gnatmake
-
-A typical development cycle when working on an Ada program consists of
-the following steps:
-
-
-@enumerate 
-
-@item 
-Edit some sources to fix bugs;
-
-@item 
-Add enhancements;
-
-@item 
-Compile all sources affected;
-
-@item 
-Rebind and relink; and
-
-@item 
-Test.
-@end enumerate
-
-@geindex Dependency rules (compilation)
-
-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, @code{use} clauses, generics and inlined
-subprograms.
-
-@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.
-
-Unlike some other Ada make programs, the dependencies are always
-accurately recomputed from the new sources. The source based approach of
-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
-@code{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
-@code{gprbuild} tool which supports building with project files and works similarly
-to @code{gnatmake}.
-
-@menu
-* Running gnatmake:: 
-* Switches for gnatmake:: 
-* Mode Switches for gnatmake:: 
-* Notes on the Command Line:: 
-* How gnatmake Works:: 
-* Examples of gnatmake Usage:: 
-
-@end menu
-
-@node Running gnatmake,Switches for gnatmake,,Building with gnatmake
-@anchor{gnat_ugn/building_executable_programs_with_gnat id2}@anchor{cb}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatmake}@anchor{cc}
-@subsection Running @code{gnatmake}
-
-
-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 @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 @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 @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 @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
-@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{73,,Search Paths and the Run-Time Library (RTL)}.
-
-All @code{gnatmake} output (except when you specify @code{-M}) is sent to
-@code{stderr}. The output produced by the
-@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 id3}@anchor{cd}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatmake}@anchor{ce}
-@subsection Switches for @code{gnatmake}
-
-
-You may specify any of the following switches to @code{gnatmake}:
-
-@geindex --version (gnatmake)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display Copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatmake)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
-
-@geindex -P (gnatmake)
-
-
-@table @asis
-
-@item @code{-P`project'}
-
-Build GNAT project file @code{project} using GPRbuild. When this switch is
-present, all other command-line switches are treated as GPRbuild switches
-and not @code{gnatmake} switches.
-@end table
-
-@c -- Comment:
-@c :ref:`gnatmake_and_Project_Files`.
-
-@geindex --GCC=compiler_name (gnatmake)
-
-
-@table @asis
-
-@item @code{--GCC=`compiler_name'}
-
-Program used for compiling. The default is @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{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 @code{gnatmake}
-will be @code{foo -c -x -y}. If several @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
-@code{--GCC="bar -x -y -z -t"}.
-@end table
-
-@geindex --GNATBIND=binder_name (gnatmake)
-
-
-@table @asis
-
-@item @code{--GNATBIND=`binder_name'}
-
-Program used for binding. The default is @code{gnatbind}. You need to
-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 @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
-
-@geindex --GNATLINK=linker_name (gnatmake)
-
-
-@table @asis
-
-@item @code{--GNATLINK=`linker_name'}
-
-Program used for linking. The default is @code{gnatlink}. You need to
-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 @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
-itself must not include any embedded spaces.
-
-@item @code{--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”.
-
-@item @code{--create-map-file=`mapfile'}
-
-When linking an executable, create a map file with the specified name.
-@end table
-
-@geindex --create-missing-dirs (gnatmake)
-
-
-@table @asis
-
-@item @code{--create-missing-dirs}
-
-When using project files (@code{-P`project'}), automatically create
-missing object directories, library directories and exec
-directories.
-
-@item @code{--single-compile-per-obj-dir}
-
-Disallow simultaneous compilations in the same object directory when
-project files are used.
-
-@item @code{--subdirs=`subdir'}
-
-Actual object directory of each project file is the subdirectory subdir of the
-object directory specified or defaulted in the project file.
-
-@item @code{--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.
-
-@item @code{--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
-does not exist, then after the Project Manager has successfully parsed and
-processed the project files and found the sources, it creates the source info
-file. If the source info file already exists and can be read successfully,
-then the Project Manager will get all the needed information about the sources
-from the source info file and will not look for them. This reduces the time
-to process the project files, especially when looking for sources that take a
-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. @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
-
-@geindex -a (gnatmake)
-
-
-@table @asis
-
-@item @code{-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,
-@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
-of these files is not up to date, it will be properly caught by the
-binder.
-You may have to specify this switch if you are working on GNAT
-itself. The switch @code{-a} is also useful
-in conjunction with @code{-f}
-if you need to recompile an entire application,
-including run-time files, using special configuration pragmas,
-such as a @code{Normalize_Scalars} pragma.
-
-By default
-@code{gnatmake -a} compiles all GNAT
-internal files with
-@code{gcc -c -gnatpg} rather than @code{gcc -c}.
-@end table
-
-@geindex -b (gnatmake)
-
-
-@table @asis
-
-@item @code{-b}
-
-Bind only. Can be combined with @code{-c} to do
-compilation and binding, but no link.
-Can be combined with @code{-l}
-to do binding and linking. When not combined with
-@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 @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
-
-@geindex -c (gnatmake)
-
-
-@table @asis
-
-@item @code{-c}
-
-Compile only. Do not perform binding, except when @code{-b}
-is also specified. Do not perform linking, except if both
-@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
-
-@geindex -C (gnatmake)
-
-
-@table @asis
-
-@item @code{-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
-@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
-@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
-
-@geindex -C= (gnatmake)
-
-
-@table @asis
-
-@item @code{-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.
-This switch is not compatible with a project file
-(-P`file`) or with multiple compiling processes
-(-jnnn, when nnn is greater than 1).
-@end table
-
-@geindex -d (gnatmake)
-
-
-@table @asis
-
-@item @code{-d}
-
-Display progress for each source, up to date or not, as a single line:
-
-@example
-completed x out of y (zz%)
-@end example
-
-If the file needs to be compiled this is displayed after the invocation of
-the compiler. These lines are displayed even in quiet output mode.
-@end table
-
-@geindex -D (gnatmake)
-
-
-@table @asis
-
-@item @code{-D `dir'}
-
-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.
-@end table
-
-@geindex -eI (gnatmake)
-
-
-@table @asis
-
-@item @code{-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 @code{gnatmake} is
-invoked for several mains.
-@end table
-
-@geindex -eL (gnatmake)
-
-@geindex symbolic links
-
-
-@table @asis
-
-@item @code{-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.
-
-@geindex naming scheme
-
-This also assumes that no directory matches the naming scheme for files (for
-instance that you do not have a directory called “sources.ads” when using the
-default GNAT naming scheme).
-
-When you do not have to use this switch (i.e., by default), gnatmake is able to
-save a lot of system calls (several per source file and object file), which
-can result in a significant speed up to load and manipulate a project file,
-especially when using source files from a remote system.
-@end table
-
-@geindex -eS (gnatmake)
-
-
-@table @asis
-
-@item @code{-eS}
-
-Output the commands for the compiler, the binder and the linker
-on standard output,
-instead of standard error.
-@end table
-
-@geindex -f (gnatmake)
-
-
-@table @asis
-
-@item @code{-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 @code{-a} switch is also specified.
-@end table
-
-@geindex -F (gnatmake)
-
-
-@table @asis
-
-@item @code{-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
-file, rather than its simple file name.
-@end table
-
-@geindex -g (gnatmake)
-
-
-@table @asis
-
-@item @code{-g}
-
-Enable debugging. This switch is simply passed to the compiler and to the
-linker.
-@end table
-
-@geindex -i (gnatmake)
-
-
-@table @asis
-
-@item @code{-i}
-
-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 @code{gnatmake} will automatically
-maintain and update this organization. If no ALI files are found on the
-Ada object path (see @ref{73,,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, @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
-
-@geindex -j (gnatmake)
-
-@geindex Parallel make
-
-
-@table @asis
-
-@item @code{-j`n'}
-
-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 @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
-
-@geindex -k (gnatmake)
-
-
-@table @asis
-
-@item @code{-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 @code{gnatmake}
-terminates.
-
-If @code{gnatmake} is invoked with several @code{file_names} and with this
-switch, if there are compilation errors when building an executable,
-@code{gnatmake} will not attempt to build the following executables.
-@end table
-
-@geindex -l (gnatmake)
-
-
-@table @asis
-
-@item @code{-l}
-
-Link only. Can be combined with @code{-b} to binding
-and linking. Linking will not be performed if combined with
-@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 @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
-
-@geindex -m (gnatmake)
-
-
-@table @asis
-
-@item @code{-m}
-
-Specify that the minimum necessary amount of recompilations
-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 @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 @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
-
-@geindex Dependencies
-@geindex producing list
-
-@geindex -M (gnatmake)
-
-
-@table @asis
-
-@item @code{-M}
-
-Check if all objects are up to date. If they are, output the object
-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 @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  @code{-M}
-switch, dependencies of the GNAT internal system files are omitted. This
-is typically what you want. If you also specify
-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`dir'} in the following list)
-are never reported.
-@end table
-
-@geindex -n (gnatmake)
-
-
-@table @asis
-
-@item @code{-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.
-Repeated use of this option, followed by compiling the indicated source
-file, will eventually result in recompiling all required units.
-@end table
-
-@geindex -o (gnatmake)
-
-
-@table @asis
-
-@item @code{-o `exec_name'}
-
-Output executable name. The name of the final executable program will be
-@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 @code{gnatmake} with several
-@code{file_names}.
-@end table
-
-@geindex -p (gnatmake)
-
-
-@table @asis
-
-@item @code{-p}
-
-Same as @code{--create-missing-dirs}
-@end table
-
-@geindex -q (gnatmake)
-
-
-@table @asis
-
-@item @code{-q}
-
-Quiet. When this flag is not set, the commands carried out by
-@code{gnatmake} are displayed.
-@end table
-
-@geindex -s (gnatmake)
-
-
-@table @asis
-
-@item @code{-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,
-@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
-
-@geindex -u (gnatmake)
-
-
-@table @asis
-
-@item @code{-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.
-@end table
-
-@c --Comment
-@c (See :ref:`Project_Files_and_Main_Subprograms`.)
-
-@geindex -U (gnatmake)
-
-
-@table @asis
-
-@item @code{-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
-if not up to date, and libraries are rebuilt, if necessary.
-@end table
-
-@geindex -v (gnatmake)
-
-
-@table @asis
-
-@item @code{-v}
-
-Verbose. Display the reason for all recompilations @code{gnatmake}
-decides are necessary, with the highest verbosity level.
-@end table
-
-@geindex -vl (gnatmake)
-
-
-@table @asis
-
-@item @code{-vl}
-
-Verbosity level Low. Display fewer lines than in verbosity Medium.
-@end table
-
-@geindex -vm (gnatmake)
-
-
-@table @asis
-
-@item @code{-vm}
-
-Verbosity level Medium. Potentially display fewer lines than in verbosity High.
-@end table
-
-@geindex -vm (gnatmake)
-
-
-@table @asis
-
-@item @code{-vh}
-
-Verbosity level High. Equivalent to -v.
-
-@item @code{-vP`x'}
-
-Indicate the verbosity of the parsing of GNAT project files.
-See @ref{cf,,Switches Related to Project Files}.
-@end table
-
-@geindex -x (gnatmake)
-
-
-@table @asis
-
-@item @code{-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
-@code{-x} is used, mains specified on the
-command line need to be sources of a project file.
-
-@item @code{-X`name'=`value'}
-
-Indicate that external variable @code{name} has the value @code{value}.
-The Project Manager will use this value for occurrences of
-@code{external(name)} when parsing the project file.
-@ref{cf,,Switches Related to Project Files}.
-@end table
-
-@geindex -z (gnatmake)
-
-
-@table @asis
-
-@item @code{-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,
-then the finalization routines.
-@end table
-
-@subsubheading GCC switches
-
-
-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
-
-
-@geindex -aI (gnatmake)
-
-
-@table @asis
-
-@item @code{-aI`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{73,,Search Paths and the Run-Time Library (RTL)}.
-@end table
-
-@geindex -aL (gnatmake)
-
-
-@table @asis
-
-@item @code{-aL`dir'}
-
-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`dir'}  or @code{-I`dir'}.
-Note: this switch is provided for compatibility with previous versions
-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
-
-@geindex -aO (gnatmake)
-
-
-@table @asis
-
-@item @code{-aO`dir'}
-
-When searching for library and object files, look in directory
-@code{dir}. The order in which library files are searched is described in
-@ref{76,,Search Paths for gnatbind}.
-@end table
-
-@geindex Search paths
-@geindex for gnatmake
-
-@geindex -A (gnatmake)
-
-
-@table @asis
-
-@item @code{-A`dir'}
-
-Equivalent to @code{-aL`dir'} @code{-aI`dir'}.
-
-@geindex -I (gnatmake)
-
-@item @code{-I`dir'}
-
-Equivalent to @code{-aO`dir' -aI`dir'}.
-@end table
-
-@geindex -I- (gnatmake)
-
-@geindex Source files
-@geindex suppressing search
-
-
-@table @asis
-
-@item @code{-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 @code{gnatmake} was invoked.
-@end table
-
-@geindex -L (gnatmake)
-
-@geindex Linker libraries
-
-
-@table @asis
-
-@item @code{-L`dir'}
-
-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`dir'}.
-Furthermore, under Windows, the sources pointed to by the libraries path
-set in the registry are not searched for.
-@end table
-
-@geindex -nostdinc (gnatmake)
-
-
-@table @asis
-
-@item @code{-nostdinc}
-
-Do not look for source files in the system default directory.
-@end table
-
-@geindex -nostdlib (gnatmake)
-
-
-@table @asis
-
-@item @code{-nostdlib}
-
-Do not look for library files in the system default directory.
-@end table
-
-@geindex --RTS (gnatmake)
-
-
-@table @asis
-
-@item @code{--RTS=`rts-path'}
-
-Specifies the default location of the run-time library. GNAT looks for the
-run-time
-in the following directories, and stops as soon as a valid run-time is found
-(@code{adainclude} or @code{ada_source_path}, and @code{adalib} or
-@code{ada_object_path} present):
-
-
-@itemize *
-
-@item 
-`<current directory>/$rts_path'
-
-@item 
-`<default-search-dir>/$rts_path'
-
-@item 
-`<default-search-dir>/rts-$rts_path'
-
-@item 
-The selected path is handled like a normal RTS path.
-@end itemize
-@end table
-
-@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{d0}@anchor{gnat_ugn/building_executable_programs_with_gnat mode-switches-for-gnatmake}@anchor{d1}
-@subsection Mode Switches for @code{gnatmake}
-
-
-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
-mode switch, to be interpreted as switches to be passed on to the
-designated component of GNAT.
-
-@geindex -cargs (gnatmake)
-
-
-@table @asis
-
-@item @code{-cargs `switches'}
-
-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)
-
-
-@table @asis
-
-@item @code{-bargs `switches'}
-
-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)
-
-
-@table @asis
-
-@item @code{-largs `switches'}
-
-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)
-
-
-@table @asis
-
-@item @code{-margs `switches'}
-
-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
-@anchor{gnat_ugn/building_executable_programs_with_gnat id5}@anchor{d2}@anchor{gnat_ugn/building_executable_programs_with_gnat notes-on-the-command-line}@anchor{d3}
-@subsection Notes on the Command Line
-
-
-This section contains some additional useful notes on the operation
-of the @code{gnatmake} command.
-
-@geindex Recompilation (by gnatmake)
-
-
-@itemize *
-
-@item 
-If @code{gnatmake} finds no ALI files, it recompiles the main program
-and all other units required by the main program.
-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, @code{gnatmake} recompiles
-@code{foo.adb} (because it finds no ALI) and stops, issuing a
-warning.
-
-@item 
-In @code{gnatmake} the switch @code{-I}
-is used to specify both source and
-library file paths. Use @code{-aI}
-instead if you just want to specify
-source paths only and @code{-aO}
-if you want to specify library paths
-only.
-
-@item 
-@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
-@code{-f} switch will not recompile these files
-unless @code{-a} is also specified.
-
-@item 
-@code{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 @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 @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
-source files without having to recompile everything. Note, however, that
-adding or deleting lines in a source files may render its debugging
-info obsolete. If the file in question is a spec, the impact is rather
-limited, as that debugging info will only be useful during the
-elaboration phase of your program. For bodies the impact can be more
-significant. In all events, your debugger will warn you if a source file
-is more recent than the corresponding object, and alert you to the fact
-that the debugging information may be out of date.
-@end itemize
-
-@node How gnatmake Works,Examples of gnatmake Usage,Notes on the Command Line,Building with gnatmake
-@anchor{gnat_ugn/building_executable_programs_with_gnat how-gnatmake-works}@anchor{d4}@anchor{gnat_ugn/building_executable_programs_with_gnat id6}@anchor{d5}
-@subsection How @code{gnatmake} Works
-
-
-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 @code{gnatmake}
-approach and in particular to understand how it uses the results of
-previous compilations without incorrectly depending on them.
-
-First a definition: an object file is considered `up to date' if the
-corresponding ALI file exists and if all the source files listed in the
-dependency section of this ALI file have time stamps matching those in
-the ALI file. This means that neither the source file itself nor any
-files that it depends on have been modified, and hence there is no need
-to recompile this file.
-
-@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,
-@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 @code{gnatmake} recursively applies the above procedure on all these
-files.
-
-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
-be more familiar as the required order of compilation in some other Ada
-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
-@code{gnatmake} will recompute a correct set of new dependencies if
-necessary.
-
-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{1c,,Using Other File Names}), changing through a configuration pragmas
-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 @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{d6}@anchor{gnat_ugn/building_executable_programs_with_gnat id7}@anchor{d7}
-@subsection Examples of @code{gnatmake} Usage
-
-
-
-@table @asis
-
-@item `gnatmake hello.adb'
-
-Compile all files necessary to bind and link the main program
-@code{hello.adb} (containing unit @code{Hello}) and bind and link the
-resulting object files to generate an executable file @code{hello}.
-
-@item `gnatmake main1 main2 main3'
-
-Compile all files necessary to bind and link the main programs
-@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 `gnatmake -q Main_Unit -cargs -O2 -bargs -l'
-
-Compile all files necessary to bind and link the main program unit
-@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. @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{c7}@anchor{gnat_ugn/building_executable_programs_with_gnat id8}@anchor{d8}
-@section Compiling with @code{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.
-
-@menu
-* Compiling Programs:: 
-* Search Paths and the Run-Time Library (RTL): Search Paths and the Run-Time Library RTL. 
-* Order of Compilation Issues:: 
-* Examples:: 
-
-@end menu
-
-@node Compiling Programs,Search Paths and the Run-Time Library RTL,,Compiling with gcc
-@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-programs}@anchor{d9}@anchor{gnat_ugn/building_executable_programs_with_gnat id9}@anchor{da}
-@subsection Compiling Programs
-
-
-The first step in creating an executable program is to compile the units
-of the program using the @code{gcc} command. You must compile the
-following files:
-
-
-@itemize *
-
-@item 
-the body file (@code{.adb}) for a library level subprogram or generic
-subprogram
-
-@item 
-the spec file (@code{.ads}) for a library level package or generic
-package that has no body
-
-@item 
-the body file (@code{.adb}) for a library level package
-or generic package that has a body
-@end itemize
-
-You need `not' compile the following files
-
-
-@itemize *
-
-@item 
-the spec of a library unit which has a body
-
-@item 
-subunits
-@end itemize
-
-because they are compiled as part of compiling related units. GNAT
-package specs
-when the corresponding body is compiled, and subunits when the parent is
-compiled.
-
-@geindex cannot generate code
-
-If you attempt to compile any of these files, you will get one of the
-following error messages (where @code{fff} is the name of the file you
-compiled):
-
-@quotation
-
-@example
-cannot generate code for file `@w{`}fff`@w{`} (package spec)
-to check package spec, use -gnatc
-
-cannot generate code for file `@w{`}fff`@w{`} (missing subunits)
-to check parent unit, use -gnatc
-
-cannot generate code for file `@w{`}fff`@w{`} (subprogram spec)
-to check subprogram spec, use -gnatc
-
-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 @code{-gnatc} switch.
-
-The basic command for compiling a file containing an Ada unit is:
-
-@example
-$ gcc -c [switches] <file name>
-@end example
-
-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 @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
-source file, but with @code{.ali} as the extension. GNAT creates these
-two output files in the current directory, but you may specify a source
-file in any directory using an absolute or relative path specification
-containing the directory information.
-
-TESTING: the @code{--foobar`NN'} switch
-
-@geindex gnat1
-
-@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 @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 @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:
-
-@example
-$ gcc -c x.adb y.adb
-@end example
-
-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{db,,Compiler Switches} for a
-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{dc}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-and-the-run-time-library-rtl}@anchor{73}
-@subsection Search Paths and the Run-Time Library (RTL)
-
-
-With the GNAT source-based library system, the compiler must be able to
-find source files for units that are needed by the unit being compiled.
-Search paths are used to guide this process.
-
-The compiler compiles one source file whose name must be given
-explicitly on the command line. In other words, no searching is done
-for this file. To find all other source files that are needed (the most
-common being the specs of units), the compiler examines the following
-directories, in the following order:
-
-
-@itemize *
-
-@item 
-The directory containing the source file of the main unit being compiled
-(the file name on the command line).
-
-@item 
-Each directory named by an @code{-I} switch given on the @code{gcc}
-command line, in the order given.
-
-@geindex ADA_PRJ_INCLUDE_FILE
-
-@item 
-Each of the directories listed in the text file whose name is given
-by the 
-@geindex ADA_PRJ_INCLUDE_FILE
-@geindex environment variable; ADA_PRJ_INCLUDE_FILE
-@code{ADA_PRJ_INCLUDE_FILE} environment variable.
-@geindex ADA_PRJ_INCLUDE_FILE
-@geindex environment variable; ADA_PRJ_INCLUDE_FILE
-@code{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the gnat
-driver when project files are used. It should not normally be set
-by other means.
-
-@geindex ADA_INCLUDE_PATH
-
-@item 
-Each of the directories listed in the value of the
-@geindex ADA_INCLUDE_PATH
-@geindex environment variable; ADA_INCLUDE_PATH
-@code{ADA_INCLUDE_PATH} environment variable.
-Construct this value
-exactly as the 
-@geindex PATH
-@geindex environment variable; PATH
-@code{PATH} environment variable: a list of directory
-names separated by colons (semicolons when working with the NT version).
-
-@item 
-The content of the @code{ada_source_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) source files.
-@ref{72,,Installing a library}
-@end itemize
-
-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 @code{-I} switch.
-
-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 @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 @code{-o} switch.
-
-@geindex System.IO
-
-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 (@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.
-
-Besides simplifying access to the RTL, a major use of search paths is
-in compiling sources from multiple directories. This can make
-development environments much more flexible.
-
-@node Order of Compilation Issues,Examples,Search Paths and the Run-Time Library RTL,Compiling with gcc
-@anchor{gnat_ugn/building_executable_programs_with_gnat id11}@anchor{dd}@anchor{gnat_ugn/building_executable_programs_with_gnat order-of-compilation-issues}@anchor{de}
-@subsection Order of Compilation Issues
-
-
-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
-of this model are as follows:
-
-
-@itemize *
-
-@item 
-There is no point in compiling specs (except for package
-specs with no bodies) because these are compiled as needed by clients. If
-you attempt a useless compilation, you will receive an error message.
-It is also useless to compile subunits because they are compiled as needed
-by the parent.
-
-@item 
-There are no order of compilation requirements: performing a
-compilation never obsoletes anything. The only way you can obsolete
-something and require recompilations is to modify one of the
-source files on which it depends.
-
-@item 
-There is no library as such, apart from the ALI files
-(@ref{28,,The Ada Library Information Files}, for information on the format
-of these files). For now we find it convenient to create separate ALI files,
-but eventually the information therein may be incorporated into the object
-file directly.
-
-@item 
-When you compile a unit, the source files for the specs of all units
-that it `with's, all its subunits, and the bodies of any generics it
-instantiates must be available (reachable by the search-paths mechanism
-described above), or you will receive a fatal error message.
-@end itemize
-
-@node Examples,,Order of Compilation Issues,Compiling with gcc
-@anchor{gnat_ugn/building_executable_programs_with_gnat examples}@anchor{df}@anchor{gnat_ugn/building_executable_programs_with_gnat id12}@anchor{e0}
-@subsection Examples
-
-
-The following are some typical Ada compilation command line examples:
-
-@example
-$ gcc -c xyz.adb
-@end example
-
-Compile body in file @code{xyz.adb} with all default options.
-
-@example
-$ gcc -c -O2 -gnata xyz-def.adb
-@end example
-
-Compile the child unit package in file @code{xyz-def.adb} with extensive
-optimizations, and pragma @code{Assert}/@cite{Debug} statements
-enabled.
-
-@example
-$ gcc -c -gnatc abc-def.adb
-@end example
-
-Compile the subunit in file @code{abc-def.adb} in semantic-checking-only
-mode.
-
-@node Compiler Switches,Linker Switches,Compiling with gcc,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat compiler-switches}@anchor{e1}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gcc}@anchor{db}
-@section Compiler Switches
-
-
-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
-information.
-
-More switches exist for GCC than those documented here, especially
-for specific targets. However, their use is not recommended as
-they may change code generation in ways that are incompatible with
-the Ada run-time library, or can cause inconsistencies between
-compilation units.
-
-@menu
-* Alphabetical List of All Switches:: 
-* Output and Error Message Control:: 
-* Warning Message Control:: 
-* Debugging and Assertion Control:: 
-* Validity Checking:: 
-* Style Checking:: 
-* Run-Time Checks:: 
-* Using gcc for Syntax Checking:: 
-* Using gcc for Semantic Checking:: 
-* Compiling Different Versions of Ada:: 
-* Character Set Control:: 
-* File Naming Control:: 
-* Subprogram Inlining Control:: 
-* Auxiliary Output Control:: 
-* Debugging Control:: 
-* Exception Handling Control:: 
-* Units to Sources Mapping Files:: 
-* Code Generation Control:: 
-
-@end menu
-
-@node Alphabetical List of All Switches,Output and Error Message Control,,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat alphabetical-list-of-all-switches}@anchor{e2}@anchor{gnat_ugn/building_executable_programs_with_gnat id13}@anchor{e3}
-@subsection Alphabetical List of All Switches
-
-
-@geindex -b (gcc)
-
-
-@table @asis
-
-@item @code{-b `target'}
-
-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
-@code{target} is not the same as your host system.
-@end table
-
-@geindex -B (gcc)
-
-
-@table @asis
-
-@item @code{-B`dir'}
-
-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 @code{-b} or @code{-V} switch instead.
-@end table
-
-@geindex -c (gcc)
-
-
-@table @asis
-
-@item @code{-c}
-
-Compile. Always use this switch when compiling Ada programs.
-
-Note: for some other languages when using @code{gcc}, notably in
-the case of C and C++, it is possible to use
-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 @code{gcc} cannot be used to run the GNAT binder.
-@end table
-
-@geindex -fcallgraph-info (gcc)
-
-
-@table @asis
-
-@item @code{-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
-@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
-
-@geindex -fdiagnostics-format (gcc)
-
-
-@table @asis
-
-@item @code{-fdiagnostics-format=json}
-
-Makes GNAT emit warning and error messages as JSON. Inhibits printing of
-text warning and errors messages except if @code{-gnatv} or
-@code{-gnatl} are present. Uses absolute file paths when used along
-@code{-gnatef}.
-@end table
-
-@geindex -fdump-scos (gcc)
-
-
-@table @asis
-
-@item @code{-fdump-scos}
-
-Generates SCO (Source Coverage Obligation) information in the ALI file.
-This information is used by advanced coverage tools. See unit @code{SCOs}
-in the compiler sources for details in files @code{scos.ads} and
-@code{scos.adb}.
-@end table
-
-@geindex -fgnat-encodings (gcc)
-
-
-@table @asis
-
-@item @code{-fgnat-encodings=[all|gdb|minimal]}
-
-This switch controls the balance between GNAT encodings and standard DWARF
-emitted in the debug information.
-@end table
-
-@geindex -flto (gcc)
-
-
-@table @asis
-
-@item @code{-flto[=`n']}
-
-Enables Link Time Optimization. This switch must be used in conjunction
-with the @code{-Ox} switches (but not with the @code{-gnatn} switch
-since it is a full replacement for the latter) 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 units 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 @code{-Ox} switches, must be
-specified both for the compilation and the link phases.
-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)
-
-
-@table @asis
-
-@item @code{-fno-inline}
-
-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 @code{No_Inline}.
-@end table
-
-@geindex -fno-inline-functions (gcc)
-
-
-@table @asis
-
-@item @code{-fno-inline-functions}
-
-Suppresses automatic inlining of subprograms, which is enabled
-if @code{-O3} is used.
-@end table
-
-@geindex -fno-inline-small-functions (gcc)
-
-
-@table @asis
-
-@item @code{-fno-inline-small-functions}
-
-Suppresses automatic inlining of small subprograms, which is enabled
-if @code{-O2} is used.
-@end table
-
-@geindex -fno-inline-functions-called-once (gcc)
-
-
-@table @asis
-
-@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 @code{-O1} is used.
-@end table
-
-@geindex -fno-ivopts (gcc)
-
-
-@table @asis
-
-@item @code{-fno-ivopts}
-
-Suppresses high-level loop induction variable optimizations, which are
-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
-and thus producing inferior code.
-@end table
-
-@geindex -fno-strict-aliasing (gcc)
-
-
-@table @asis
-
-@item @code{-fno-strict-aliasing}
-
-Causes the compiler to avoid assumptions regarding non-aliasing
-of objects of different types. See
-@ref{e4,,Optimization and Strict Aliasing} for details.
-@end table
-
-@geindex -fno-strict-overflow (gcc)
-
-
-@table @asis
-
-@item @code{-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 @code{-gnato0}
-for very peculiar cases of low-level programming.
-@end table
-
-@geindex -fstack-check (gcc)
-
-
-@table @asis
-
-@item @code{-fstack-check}
-
-Activates stack checking.
-See @ref{e5,,Stack Overflow Checking} for details.
-@end table
-
-@geindex -fstack-usage (gcc)
-
-
-@table @asis
-
-@item @code{-fstack-usage}
-
-Makes the compiler output stack usage information for the program, on a
-per-subprogram basis. See @ref{e6,,Static Stack Usage Analysis} for details.
-@end table
-
-@geindex -g (gcc)
-
-
-@table @asis
-
-@item @code{-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
-@code{-g} switch if you plan on using the debugger.
-@end table
-
-@geindex -gnat05 (gcc)
-
-
-@table @asis
-
-@item @code{-gnat05}
-
-Allow full Ada 2005 features.
-@end table
-
-@geindex -gnat12 (gcc)
-
-
-@table @asis
-
-@item @code{-gnat12}
-
-Allow full Ada 2012 features.
-@end table
-
-@geindex -gnat83 (gcc)
-
-@geindex -gnat2005 (gcc)
-
-
-@table @asis
-
-@item @code{-gnat2005}
-
-Allow full Ada 2005 features (same as @code{-gnat05})
-@end table
-
-@geindex -gnat2012 (gcc)
-
-
-@table @asis
-
-@item @code{-gnat2012}
-
-Allow full Ada 2012 features (same as @code{-gnat12})
-@end table
-
-@geindex -gnat2022 (gcc)
-
-
-@table @asis
-
-@item @code{-gnat2022}
-
-Allow full Ada 2022 features
-
-@item @code{-gnat83}
-
-Enforce Ada 83 restrictions.
-@end table
-
-@geindex -gnat95 (gcc)
-
-
-@table @asis
-
-@item @code{-gnat95}
-
-Enforce Ada 95 restrictions.
-
-Note: for compatibility with some Ada 95 compilers which support only
-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.
-
-@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
-
-@geindex -gnata (gcc)
-
-
-@table @asis
-
-@item @code{-gnata}
-
-Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
-activated. Note that these pragmas can also be controlled using the
-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
-also activated. The default is that all these assertions are disabled,
-and have no effect, other than being checked for syntactic validity, and
-in the case of subtype predicates, constructions such as membership tests
-still test predicates even if assertions are turned off.
-@end table
-
-@geindex -gnatA (gcc)
-
-
-@table @asis
-
-@item @code{-gnatA}
-
-Avoid processing @code{gnat.adc}. If a @code{gnat.adc} file is present,
-it will be ignored.
-@end table
-
-@geindex -gnatb (gcc)
-
-
-@table @asis
-
-@item @code{-gnatb}
-
-Generate brief messages to @code{stderr} even if verbose mode set.
-@end table
-
-@geindex -gnatB (gcc)
-
-
-@table @asis
-
-@item @code{-gnatB}
-
-Assume no invalid (bad) values except for ‘Valid attribute use
-(@ref{e7,,Validity Checking}).
-@end table
-
-@geindex -gnatc (gcc)
-
-
-@table @asis
-
-@item @code{-gnatc}
-
-Check syntax and semantics only (no code generation attempted). When the
-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
-
-@geindex -gnatC (gcc)
-
-
-@table @asis
-
-@item @code{-gnatC}
-
-Generate CodePeer intermediate format (no code generation attempted).
-This switch will generate an intermediate representation suitable for
-use by CodePeer (@code{.scil} files). This switch is not compatible with
-code generation (it will, among other things, disable some switches such
-as -gnatn, and enable others such as -gnata).
-@end table
-
-@geindex -gnatd (gcc)
-
-
-@table @asis
-
-@item @code{-gnatd}
-
-Specify debug options for the compiler. The string of characters after
-the @code{-gnatd} specifies the specific debug options. The possible
-characters are 0-9, a-z, A-Z, optionally preceded by a dot or underscore.
-See compiler source file @code{debug.adb} for details of the implemented
-debug options. Certain debug options are relevant to applications
-programmers, and these are documented at appropriate points in this
-users guide.
-@end table
-
-@geindex -gnatD[nn] (gcc)
-
-
-@table @asis
-
-@item @code{-gnatD}
-
-Create expanded source files for source level debugging. This switch
-also suppresses generation of cross-reference information
-(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
-
-@geindex -gnateA (gcc)
-
-
-@table @asis
-
-@item @code{-gnateA}
-
-Check that the actual parameters of a subprogram call are not aliases of one
-another. To qualify as aliasing, their memory locations must be identical or
-overlapping, at least one of the corresponding formal parameters must be of
-mode OUT or IN OUT, and at least one of the corresponding formal parameters
-must have its parameter passing mechanism not specified.
-
-@example
-type Rec_Typ is record
-   Data : Integer := 0;
-end record;
-
-function Self (Val : Rec_Typ) return Rec_Typ is
-begin
-   return Val;
-end Self;
-
-procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is
-begin
-   null;
-end Detect_Aliasing;
-
-Obj : Rec_Typ;
-
-Detect_Aliasing (Obj, Obj);
-Detect_Aliasing (Obj, Self (Obj));
-@end example
-
-In the example above, the first call to @code{Detect_Aliasing} fails with a
-@code{Program_Error} at run time 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 -gnateb (gcc)
-
-
-@table @asis
-
-@item @code{-gnateb}
-
-Store configuration files by their basename in ALI files. This switch is
-used for instance by gprbuild for distributed builds in order to prevent
-issues where machine-specific absolute paths could end up being stored in
-ALI files.
-@end table
-
-@geindex -gnatec (gcc)
-
-
-@table @asis
-
-@item @code{-gnatec=`path'}
-
-Specify a configuration pragma file
-(the equal sign is optional)
-(@ref{63,,The Configuration Pragmas Files}).
-@end table
-
-@geindex -gnateC (gcc)
-
-
-@table @asis
-
-@item @code{-gnateC}
-
-Generate CodePeer messages in a compiler-like format. This switch is only
-effective if @code{-gnatcC} is also specified and requires an installation
-of CodePeer.
-@end table
-
-@geindex -gnated (gcc)
-
-
-@table @asis
-
-@item @code{-gnated}
-
-Disable atomic synchronization
-@end table
-
-@geindex -gnateD (gcc)
-
-
-@table @asis
-
-@item @code{-gnateDsymbol[=`value']}
-
-Defines a symbol, associated with @code{value}, for preprocessing.
-(@ref{90,,Integrated Preprocessing}).
-@end table
-
-@geindex -gnateE (gcc)
-
-
-@table @asis
-
-@item @code{-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.
-In cases where the compiler is able to determine at compile time that
-a check will fail, it gives a warning, and the extra information is not
-produced at run time.
-@end table
-
-@geindex -gnatef (gcc)
-
-
-@table @asis
-
-@item @code{-gnatef}
-
-Display full source path name in brief error messages and absolute paths in
-@code{-fdiagnostics-format=json}’s output.
-@end table
-
-@geindex -gnateF (gcc)
-
-
-@table @asis
-
-@item @code{-gnateF}
-
-Check for overflow on all floating-point operations, including those
-for unconstrained predefined types. See description of pragma
-@code{Check_Float_Overflow} in GNAT RM.
-@end table
-
-@geindex -gnateg (gcc)
-
-@code{-gnateg}
-@code{-gnatceg}
-
-@quotation
-
-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{b7,,Generating C Headers for Ada Specifications} for more
-information.
-@end quotation
-
-@geindex -gnateG (gcc)
-
-
-@table @asis
-
-@item @code{-gnateG}
-
-Save result of preprocessing in a text file.
-@end table
-
-@geindex -gnatei (gcc)
-
-
-@table @asis
-
-@item @code{-gnatei`nnn'}
-
-Set maximum number of instantiations during compilation of a single unit to
-@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
-
-@geindex -gnateI (gcc)
-
-
-@table @asis
-
-@item @code{-gnateI`nnn'}
-
-Indicates that the source is a multi-unit source and that the index of the
-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
-
-@geindex -gnatel (gcc)
-
-
-@table @asis
-
-@item @code{-gnatel}
-
-This switch can be used with the static elaboration model to issue info
-messages showing
-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
-further details. These messages are not generated by default, and are
-intended only for temporary use when debugging circularity problems.
-@end table
-
-@geindex -gnatel (gcc)
-
-
-@table @asis
-
-@item @code{-gnateL}
-
-This switch turns off the info messages about implicit elaboration pragmas.
-@end table
-
-@geindex -gnatem (gcc)
-
-
-@table @asis
-
-@item @code{-gnatem=`path'}
-
-Specify a mapping file
-(the equal sign is optional)
-(@ref{e8,,Units to Sources Mapping Files}).
-@end table
-
-@geindex -gnatep (gcc)
-
-
-@table @asis
-
-@item @code{-gnatep=`file'}
-
-Specify a preprocessing data file
-(the equal sign is optional)
-(@ref{90,,Integrated Preprocessing}).
-@end table
-
-@geindex -gnateP (gcc)
-
-
-@table @asis
-
-@item @code{-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,
-these errors become warnings (which can be ignored, or suppressed in the usual
-manner). This can be useful in some specialized circumstances such as the
-temporary use of special test software.
-@end table
-
-@geindex -gnateS (gcc)
-
-
-@table @asis
-
-@item @code{-gnateS}
-
-Synonym of @code{-fdump-scos}, kept for backwards compatibility.
-@end table
-
-@geindex -gnatet=file (gcc)
-
-
-@table @asis
-
-@item @code{-gnatet=`path'}
-
-Generate target dependent information. The format of the output file is
-described in the section about switch @code{-gnateT}.
-@end table
-
-@geindex -gnateT (gcc)
-
-
-@table @asis
-
-@item @code{-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.
-This is used by tools other than the compiler, e.g. to do
-semantic analysis of programs that will run on some other target than
-the machine on which the tool is run.
-
-The following target dependent values should be defined,
-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:
-
-@example
-Bits_BE                    : Nat; -- Bits stored big-endian?
-Bits_Per_Unit              : Pos; -- Bits in a storage unit
-Bits_Per_Word              : Pos; -- Bits in a word
-Bytes_BE                   : Nat; -- Bytes stored big-endian?
-Char_Size                  : Pos; -- Standard.Character'Size
-Double_Float_Alignment     : Nat; -- Alignment of double float
-Double_Scalar_Alignment    : Nat; -- Alignment of double length scalar
-Double_Size                : Pos; -- Standard.Long_Float'Size
-Float_Size                 : Pos; -- Standard.Float'Size
-Float_Words_BE             : Nat; -- Float words stored big-endian?
-Int_Size                   : Pos; -- Standard.Integer'Size
-Long_Double_Size           : Pos; -- Standard.Long_Long_Float'Size
-Long_Long_Long_Size        : Pos; -- Standard.Long_Long_Long_Integer'Size
-Long_Long_Size             : Pos; -- Standard.Long_Long_Integer'Size
-Long_Size                  : Pos; -- Standard.Long_Integer'Size
-Maximum_Alignment          : Pos; -- Maximum permitted alignment
-Max_Unaligned_Field        : Pos; -- Maximum size for unaligned bit field
-Pointer_Size               : Pos; -- System.Address'Size
-Short_Enums                : Nat; -- Foreign enums use short size?
-Short_Size                 : Pos; -- Standard.Short_Integer'Size
-Strict_Alignment           : Nat; -- Strict alignment?
-System_Allocator_Alignment : Nat; -- Alignment for malloc calls
-Wchar_T_Size               : Pos; -- Interfaces.C.wchar_t'Size
-Words_BE                   : Nat; -- Words stored big-endian?
-@end example
-
-@code{Bits_Per_Unit} is the number of bits in a storage unit, the equivalent of
-GCC macro @code{BITS_PER_UNIT} documented as follows: @cite{Define this macro to be the number of bits in an addressable storage unit (byte); normally 8.}
-
-@code{Bits_Per_Word} is the number of bits in a machine word, the equivalent of
-GCC macro @code{BITS_PER_WORD} documented as follows: @cite{Number of bits in a word; normally 32.}
-
-@code{Double_Float_Alignment}, if not zero, is the maximum alignment that the
-compiler can choose by default for a 64-bit floating-point type or object.
-
-@code{Double_Scalar_Alignment}, if not zero, is the maximum alignment that the
-compiler can choose by default for a 64-bit or larger scalar type or object.
-
-@code{Maximum_Alignment} is the maximum alignment that the compiler can choose
-by default for a type or object, which is also the maximum alignment that can
-be specified in GNAT. It is computed for GCC backends as @code{BIGGEST_ALIGNMENT
-/ BITS_PER_UNIT} where GCC macro @code{BIGGEST_ALIGNMENT} is documented as
-follows: @cite{Biggest alignment that any data type can require on this machine@comma{} in bits.}
-
-@code{Max_Unaligned_Field} is the maximum size for unaligned bit field, which is
-64 for the majority of GCC targets (but can be different on some targets).
-
-@code{Strict_Alignment} is the equivalent of GCC macro @code{STRICT_ALIGNMENT}
-documented as follows: @cite{Define this macro to be the value 1 if instructions will fail to work if given data not on the nominal alignment. If instructions will merely go slower in that case@comma{} define this macro as 0.}
-
-@code{System_Allocator_Alignment} is the guaranteed alignment of data returned
-by calls to @code{malloc}.
-
-The format of the input file is as follows. First come the values of
-the variables defined above, with one line per value:
-
-@example
-name  value
-@end example
-
-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
-same order as the list above).
-
-Then there is a blank line to separate the two parts of the file. Then
-come the lines showing the floating-point types to be registered, with
-one line per registered mode:
-
-@example
-name  digs float_rep size alignment
-@end example
-
-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 for IEEE-754-Binary, which is
-the only one supported at this time),
-@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.
-
-Here is an example of a target parameterization file:
-
-@example
-Bits_BE                       0
-Bits_Per_Unit                 8
-Bits_Per_Word                64
-Bytes_BE                      0
-Char_Size                     8
-Double_Float_Alignment        0
-Double_Scalar_Alignment       0
-Double_Size                  64
-Float_Size                   32
-Float_Words_BE                0
-Int_Size                     64
-Long_Double_Size            128
-Long_Long_Long_Size         128
-Long_Long_Size               64
-Long_Size                    64
-Maximum_Alignment            16
-Max_Unaligned_Field          64
-Pointer_Size                 64
-Short_Size                   16
-Strict_Alignment              0
-System_Allocator_Alignment   16
-Wchar_T_Size                 32
-Words_BE                      0
-
-float         15  I  64  64
-double        15  I  64  64
-long double   18  I  80 128
-TF            33  I 128 128
-@end example
-@end table
-
-@geindex -gnateu (gcc)
-
-
-@table @asis
-
-@item @code{-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
-with an earlier version. Of course the earlier version must
-support this switch.
-@end table
-
-@geindex -gnateV (gcc)
-
-
-@table @asis
-
-@item @code{-gnateV}
-
-Check that all actual parameters of a subprogram call are valid according to
-the rules of validity checking (@ref{e7,,Validity Checking}).
-@end table
-
-@geindex -gnateY (gcc)
-
-
-@table @asis
-
-@item @code{-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
-checking options to be controlled from the command line.
-@end table
-
-@geindex -gnatE (gcc)
-
-
-@table @asis
-
-@item @code{-gnatE}
-
-Dynamic elaboration checking mode enabled. For further details see
-@ref{f,,Elaboration Order Handling in GNAT}.
-@end table
-
-@geindex -gnatf (gcc)
-
-
-@table @asis
-
-@item @code{-gnatf}
-
-Full errors. Multiple errors per line, all undefined references, do not
-attempt to suppress cascaded errors.
-@end table
-
-@geindex -gnatF (gcc)
-
-
-@table @asis
-
-@item @code{-gnatF}
-
-Externals names are folded to all uppercase.
-@end table
-
-@geindex -gnatg (gcc)
-
-
-@table @asis
-
-@item @code{-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 @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
-
-@geindex -gnatG[nn] (gcc)
-
-
-@table @asis
-
-@item @code{-gnatG=nn}
-
-List generated expanded code in source form.
-@end table
-
-@geindex -gnath (gcc)
-
-
-@table @asis
-
-@item @code{-gnath}
-
-Output usage information. The output is written to @code{stdout}.
-@end table
-
-@geindex -gnatH (gcc)
-
-
-@table @asis
-
-@item @code{-gnatH}
-
-Legacy elaboration-checking mode enabled. When this switch is in effect,
-the pre-18.x access-before-elaboration model becomes the de facto model.
-For further details see @ref{f,,Elaboration Order Handling in GNAT}.
-@end table
-
-@geindex -gnati (gcc)
-
-
-@table @asis
-
-@item @code{-gnati`c'}
-
-Identifier character set (@code{c} = 1/2/3/4/5/9/p/8/f/n/w).
-For details of the possible selections for @code{c},
-see @ref{31,,Character Set Control}.
-@end table
-
-@geindex -gnatI (gcc)
-
-
-@table @asis
-
-@item @code{-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
-problems, and also for compiling foreign code (particularly
-for use with ASIS). The representation clauses that are ignored
-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, 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.
-@end table
-
-@geindex -gnatjnn (gcc)
-
-
-@table @asis
-
-@item @code{-gnatj`nn'}
-
-Reformat error messages to fit on @code{nn} character lines
-@end table
-
-@geindex -gnatJ (gcc)
-
-
-@table @asis
-
-@item @code{-gnatJ}
-
-Permissive elaboration-checking mode enabled. When this switch is in effect,
-the post-18.x access-before-elaboration model ignores potential issues with:
-
-
-@itemize -
-
-@item 
-Accept statements
-
-@item 
-Activations of tasks defined in instances
-
-@item 
-Assertion pragmas
-
-@item 
-Calls from within an instance to its enclosing context
-
-@item 
-Calls through generic formal parameters
-
-@item 
-Calls to subprograms defined in instances
-
-@item 
-Entry calls
-
-@item 
-Indirect calls using ‘Access
-
-@item 
-Requeue statements
-
-@item 
-Select statements
-
-@item 
-Synchronous task suspension
-@end itemize
-
-and does not emit compile-time diagnostics or run-time checks. For further
-details see @ref{f,,Elaboration Order Handling in GNAT}.
-@end table
-
-@geindex -gnatk (gcc)
-
-
-@table @asis
-
-@item @code{-gnatk=`n'}
-
-Limit file names to @code{n} (1-999) characters (@code{k} = krunch).
-@end table
-
-@geindex -gnatl (gcc)
-
-
-@table @asis
-
-@item @code{-gnatl}
-
-Output full source listing with embedded error messages.
-@end table
-
-@geindex -gnatL (gcc)
-
-
-@table @asis
-
-@item @code{-gnatL}
-
-Used in conjunction with -gnatG or -gnatD to intersperse original
-source lines (as comment lines with line numbers) in the expanded
-source output.
-@end table
-
-@geindex -gnatm (gcc)
-
-
-@table @asis
-
-@item @code{-gnatm=`n'}
-
-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
-reaches this limit, then a message is output and the compilation
-is abandoned. The equal sign here is optional. A value of zero
-means that no limit applies.
-@end table
-
-@geindex -gnatn (gcc)
-
-
-@table @asis
-
-@item @code{-gnatn[12]}
-
-Activate inlining across units 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 units
-or 2 for full inlining across units. If no inlining level is specified,
-the compiler will pick it based on the optimization level.
-@end table
-
-@geindex -gnatN (gcc)
-
-
-@table @asis
-
-@item @code{-gnatN}
-
-Activate front end inlining for subprograms for which
-pragma @code{Inline} is specified. This inlining is performed
-by the front end and will be visible in the
-@code{-gnatG} output.
-
-When using a gcc-based back end, then the use of
-@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
-
-@geindex -gnato0 (gcc)
-
-
-@table @asis
-
-@item @code{-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
-@code{pragma Suppress (Overflow_Check)} in a configuration pragma file.
-@end table
-
-@geindex -gnato?? (gcc)
-
-
-@table @asis
-
-@item @code{-gnato??}
-
-Set default mode for handling generation of code to avoid intermediate
-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} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@item
-
-Digit
-
-@tab
-
-Interpretation
-
-@item
-
-`1'
-
-@tab
-
-All intermediate overflows checked against base type (@code{STRICT})
-
-@item
-
-`2'
-
-@tab
-
-Minimize intermediate overflows (@code{MINIMIZED})
-
-@item
-
-`3'
-
-@tab
-
-Eliminate intermediate overflows (@code{ELIMINATED})
-
-@end multitable
-
-
-If only one digit appears, then it applies to all
-cases; if two digits are given, then the first applies outside
-assertions, pre/postconditions, and type invariants, and the second
-applies within assertions, pre/postconditions, and type invariants.
-
-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 @code{pragma Unsuppress (Overflow_Check)} had been specified).
-
-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
-controlled by this switch (divide-by-zero checking is on by default).
-
-See also @ref{e9,,Specifying the Desired Mode}.
-@end table
-
-@geindex -gnatp (gcc)
-
-
-@table @asis
-
-@item @code{-gnatp}
-
-Suppress all checks. See @ref{ea,,Run-Time Checks} for details. This switch
-has no effect if cancelled by a subsequent @code{-gnat-p} switch.
-@end table
-
-@geindex -gnat-p (gcc)
-
-
-@table @asis
-
-@item @code{-gnat-p}
-
-Cancel effect of previous @code{-gnatp} switch.
-@end table
-
-@geindex -gnatq (gcc)
-
-
-@table @asis
-
-@item @code{-gnatq}
-
-Don’t quit. Try semantics, even if parse errors.
-@end table
-
-@geindex -gnatQ (gcc)
-
-
-@table @asis
-
-@item @code{-gnatQ}
-
-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 @code{-gnatQ} no object file is generated.
-@end table
-
-@geindex -gnatr (gcc)
-
-
-@table @asis
-
-@item @code{-gnatr}
-
-Treat pragma Restrictions as Restriction_Warnings.
-@end table
-
-@geindex -gnatR (gcc)
-
-
-@table @asis
-
-@item @code{-gnatR[0|1|2|3|4][e][j][m][s]}
-
-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)
-
-
-@table @asis
-
-@item @code{-gnats}
-
-Syntax check only.
-@end table
-
-@geindex -gnatS (gcc)
-
-
-@table @asis
-
-@item @code{-gnatS}
-
-Print package Standard.
-@end table
-
-@geindex -gnatT (gcc)
-
-
-@table @asis
-
-@item @code{-gnatT`nnn'}
-
-All compiler tables start at @code{nnn} times usual starting size.
-@end table
-
-@geindex -gnatu (gcc)
-
-
-@table @asis
-
-@item @code{-gnatu}
-
-List units for this compilation.
-@end table
-
-@geindex -gnatU (gcc)
-
-
-@table @asis
-
-@item @code{-gnatU}
-
-Tag all error messages with the unique string ‘error:’
-@end table
-
-@geindex -gnatv (gcc)
-
-
-@table @asis
-
-@item @code{-gnatv}
-
-Verbose mode. Full error output with source lines to @code{stdout}.
-@end table
-
-@geindex -gnatV (gcc)
-
-
-@table @asis
-
-@item @code{-gnatV}
-
-Control level of validity checking (@ref{e7,,Validity Checking}).
-@end table
-
-@geindex -gnatw (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw`xxx'}
-
-Warning mode where
-@code{xxx} is a string of option letters that denotes
-the exact warnings that
-are enabled or disabled (@ref{eb,,Warning Message Control}).
-@end table
-
-@geindex -gnatW (gcc)
-
-
-@table @asis
-
-@item @code{-gnatW`e'}
-
-Wide character encoding method
-(@code{e}=n/h/u/s/e/8).
-@end table
-
-@geindex -gnatx (gcc)
-
-
-@table @asis
-
-@item @code{-gnatx}
-
-Suppress generation of cross-reference information.
-@end table
-
-@geindex -gnatX (gcc)
-
-
-@table @asis
-
-@item @code{-gnatX}
-
-Enable core GNAT implementation extensions and latest Ada version.
-@end table
-
-@geindex -gnatX0 (gcc)
-
-
-@table @asis
-
-@item @code{-gnatX0}
-
-Enable all GNAT implementation extensions and latest Ada version.
-@end table
-
-@geindex -gnaty (gcc)
-
-
-@table @asis
-
-@item @code{-gnaty}
-
-Enable built-in style checks (@ref{ec,,Style Checking}).
-@end table
-
-@geindex -gnatz (gcc)
-
-
-@table @asis
-
-@item @code{-gnatz`m'}
-
-Distribution stub generation and compilation
-(@code{m}=r/c for receiver/caller stubs).
-@end table
-
-@geindex -I (gcc)
-
-
-@table @asis
-
-@item @code{-I`dir'}
-
-@geindex RTL
-
-Direct GNAT to search the @code{dir} directory for source files needed by
-the current compilation
-(see @ref{73,,Search Paths and the Run-Time Library (RTL)}).
-@end table
-
-@geindex -I- (gcc)
-
-
-@table @asis
-
-@item @code{-I-}
-
-@geindex RTL
-
-Except for the source file named in the command line, do not look for source
-files in the directory containing the source file named in the command line
-(see @ref{73,,Search Paths and the Run-Time Library (RTL)}).
-@end table
-
-@geindex -o (gcc)
-
-
-@table @asis
-
-@item @code{-o `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.
-@end table
-
-@geindex -nostdinc (gcc)
-
-
-@table @asis
-
-@item @code{-nostdinc}
-
-Inhibit the search of the default location for the GNAT Run Time
-Library (RTL) source files.
-@end table
-
-@geindex -nostdlib (gcc)
-
-
-@table @asis
-
-@item @code{-nostdlib}
-
-Inhibit the search of the default location for the GNAT Run Time
-Library (RTL) ALI files.
-@end table
-
-@geindex -O (gcc)
-
-
-@table @asis
-
-@item @code{-O[`n']}
-
-@code{n} controls the optimization level:
-
-
-@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@item
-
-`n'
-
-@tab
-
-Effect
-
-@item
-
-`0'
-
-@tab
-
-No optimization, the default setting if no @code{-O} appears
-
-@item
-
-`1'
-
-@tab
-
-Normal optimization, the default if you specify @code{-O} without an
-operand. A good compromise between code quality and compilation
-time.
-
-@item
-
-`2'
-
-@tab
-
-Extensive optimization, may improve execution time, possibly at
-the cost of substantially increased compilation time.
-
-@item
-
-`3'
-
-@tab
-
-Same as @code{-O2}, and also includes inline expansion for small
-subprograms in the same unit.
-
-@item
-
-`s'
-
-@tab
-
-Optimize space usage
-
-@end multitable
-
-
-See also @ref{ed,,Optimization Levels}.
-@end table
-
-@geindex -pass-exit-codes (gcc)
-
-
-@table @asis
-
-@item @code{-pass-exit-codes}
-
-Catch exit codes from the compiler and use the most meaningful as
-exit status.
-@end table
-
-@geindex --RTS (gcc)
-
-
-@table @asis
-
-@item @code{--RTS=`rts-path'}
-
-Specifies the default location of the run-time library. Same meaning as the
-equivalent @code{gnatmake} flag (@ref{ce,,Switches for gnatmake}).
-@end table
-
-@geindex -S (gcc)
-
-
-@table @asis
-
-@item @code{-S}
-
-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.
-This may be useful if you need to examine the generated assembly code.
-@end table
-
-@geindex -fverbose-asm (gcc)
-
-
-@table @asis
-
-@item @code{-fverbose-asm}
-
-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
-
-@geindex -v (gcc)
-
-
-@table @asis
-
-@item @code{-v}
-
-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
-
-@geindex -V (gcc)
-
-
-@table @asis
-
-@item @code{-V `ver'}
-
-Execute @code{ver} version of the compiler. This is the @code{gcc}
-version, not the GNAT version.
-@end table
-
-@geindex -w (gcc)
-
-
-@table @asis
-
-@item @code{-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 @code{-gnatws} had appeared at the start of
-the options).
-@end table
-
-@geindex Combining GNAT switches
-
-You may combine a sequence of GNAT switches into a single switch. For
-example, the combined switch
-
-@quotation
-
-@example
--gnatofi3
-@end example
-@end quotation
-
-is equivalent to specifying the following sequence of switches:
-
-@quotation
-
-@example
--gnato -gnatf -gnati3
-@end example
-@end quotation
-
-The following restrictions apply to the combination of switches
-in this manner:
-
-
-@itemize *
-
-@item 
-The switch @code{-gnatc} if combined with other switches must come
-first in the string.
-
-@item 
-The switch @code{-gnats} if combined with other switches must come
-first in the string.
-
-@item 
-The switches
-@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 @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 @code{-gnaty}
-switch), then all further characters in the switch are interpreted
-as style modifiers (see description of @code{-gnaty}).
-
-@item 
-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 @code{-gnatd}).
-
-@item 
-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 @code{-gnatw}).
-
-@item 
-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{e7,,Validity Checking}).
-
-@item 
-Option ‘em’, ‘ec’, ‘ep’, ‘l=’ and ‘R’ must be the last options in
-a combined list of options.
-@end itemize
-
-@node Output and Error Message Control,Warning Message Control,Alphabetical List of All Switches,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id14}@anchor{ee}@anchor{gnat_ugn/building_executable_programs_with_gnat output-and-error-message-control}@anchor{ef}
-@subsection Output and Error Message Control
-
-
-@geindex stderr
-
-The standard default format for error messages is called ‘brief format’.
-Brief format messages are written to @code{stderr} (the standard error
-file) and have the following form:
-
-@example
-e.adb:3:04: Incorrect spelling of keyword "function"
-e.adb:4:20: ";" should be "is"
-@end example
-
-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.
-@code{GNAT Studio} can parse the error messages
-and point to the referenced character.
-The following switches provide control over the error message
-format:
-
-@geindex -gnatv (gcc)
-
-
-@table @asis
-
-@item @code{-gnatv}
-
-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
-@code{-gnatv} switch would generate:
-
-@example
-3. funcion X (Q : Integer)
-   |
->>> Incorrect spelling of keyword "function"
-4. return Integer;
-                 |
->>> ";" should be "is"
-@end example
-
-The vertical bar indicates the location of the error, and the @code{>>>}
-prefix can be used to search for error messages. When this switch is
-used the only source lines output are those with errors.
-@end table
-
-@geindex -gnatl (gcc)
-
-
-@table @asis
-
-@item @code{-gnatl}
-
-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
-with any subunits. Typical output from compiling a package
-body @code{p.adb} might look like:
-
-@example
-Compiling: p.adb
-
-     1. package body p is
-     2.    procedure a;
-     3.    procedure a is separate;
-     4. begin
-     5.    null
-               |
-        >>> missing ";"
-
-     6. end;
-
-Compiling: p.ads
-
-     1. package p is
-     2.    pragma Elaborate_Body
-                                |
-        >>> missing ";"
-
-     3. end p;
-
-Compiling: p-a.adb
-
-     1. separate p
-                |
-        >>> missing "("
-
-     2. procedure a is
-     3. begin
-     4.    null
-               |
-        >>> missing ";"
-
-     5. end;
-@end example
-
-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.
-@end table
-
-@geindex -gnatl=fname (gcc)
-
-
-@table @asis
-
-@item @code{-gnatl=`fname'}
-
-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 @code{-gnatl=.lst},
-then the output is written to file xyz.adb.lst.
-@end table
-
-@geindex -gnatU (gcc)
-
-
-@table @asis
-
-@item @code{-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
-of error messages.
-@end table
-
-@geindex -gnatb (gcc)
-
-
-@table @asis
-
-@item @code{-gnatb}
-
-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
-format message or full listing (which as usual is written to
-@code{stdout}, the standard output file).
-@end table
-
-@geindex -gnatm (gcc)
-
-
-@table @asis
-
-@item @code{-gnatm=`n'}
-
-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
-@code{-gnatm2} might yield
-
-@example
-e.adb:3:04: Incorrect spelling of keyword "function"
-e.adb:5:35: missing ".."
-fatal error: maximum number of errors detected
-compilation abandoned
-@end example
-
-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
-reaches this limit, then a message is output and the compilation
-is abandoned. A value of zero means that no limit applies.
-
-Note that the equal sign is optional, so the switches
-@code{-gnatm2} and @code{-gnatm=2} are equivalent.
-@end table
-
-@geindex -gnatf (gcc)
-
-
-@table @asis
-
-@item @code{-gnatf}
-
-@geindex Error messages
-@geindex suppressing
-
-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
-references to undefined variables. If a given variable is referenced
-several times, the normal format of messages is
-
-@example
-e.adb:7:07: "V" is undefined (more references follow)
-@end example
-
-where the parenthetical comment warns that there are additional
-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:8:07: "V" is undefined
-e.adb:8:12: "V" is undefined
-e.adb:8:16: "V" is undefined
-e.adb:9:07: "V" is undefined
-e.adb:9:12: "V" is undefined
-@end example
-
-The @code{-gnatf} switch also generates additional information for
-some error messages.  Some examples are:
-
-
-@itemize *
-
-@item 
-Details on possibly non-portable unchecked conversion
-
-@item 
-List possible interpretations for ambiguous calls
-
-@item 
-Additional details on incorrect parameters
-@end itemize
-@end table
-
-@geindex -gnatjnn (gcc)
-
-
-@table @asis
-
-@item @code{-gnatjnn}
-
-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 @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
-is longer than nn characters.
-@end table
-
-@geindex -gnatq (gcc)
-
-
-@table @asis
-
-@item @code{-gnatq}
-
-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.
-This switch tells
-GNAT to continue with semantic analysis even if syntax errors have been
-found. This may enable the detection of more errors in a single run. On
-the other hand, the semantic analyzer is more likely to encounter some
-internal fatal error when given a syntactically invalid tree.
-@end table
-
-@geindex -gnatQ (gcc)
-
-
-@table @asis
-
-@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 @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 @code{-gnatq}, since the semantic phase must be run to get a
-meaningful ALI file.
-
-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 @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
-@anchor{gnat_ugn/building_executable_programs_with_gnat id15}@anchor{f0}@anchor{gnat_ugn/building_executable_programs_with_gnat warning-message-control}@anchor{eb}
-@subsection Warning Message Control
-
-
-@geindex Warning messages
-
-In addition to error messages, which correspond to illegalities as defined
-in the Ada Reference Manual, the compiler detects two kinds of warning
-situations.
-
-First, the compiler considers some constructs suspicious and generates a
-warning message to alert you to a possible error. Second, if the
-compiler detects a situation that is sure to raise an exception at
-run time, it generates a warning message. The following shows an example
-of warning messages:
-
-@example
-e.adb:4:24: warning: creation of object may raise Storage_Error
-e.adb:10:17: warning: static value out of range
-e.adb:10:17: warning: "Constraint_Error" will be raised at run time
-@end example
-
-GNAT considers a large number of situations as appropriate
-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
-@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
-subsequent versions of GNAT. The list is intended to give a general idea
-of the kinds of warnings that are generated.
-
-
-@itemize *
-
-@item 
-Possible infinitely recursive calls
-
-@item 
-Out-of-range values being assigned
-
-@item 
-Possible order of elaboration problems
-
-@item 
-Size not a multiple of alignment for a record type
-
-@item 
-Assertions (pragma Assert) that are sure to fail
-
-@item 
-Unreachable code
-
-@item 
-Address clauses with possibly unaligned values, or where an attempt is
-made to overlay a smaller variable with a larger one.
-
-@item 
-Fixed-point type declarations with a null range
-
-@item 
-Direct_IO or Sequential_IO instantiated with a type that has access values
-
-@item 
-Variables that are never assigned a value
-
-@item 
-Variables that are referenced before being initialized
-
-@item 
-Task entries with no corresponding @code{accept} statement
-
-@item 
-Duplicate accepts for the same task entry in a @code{select}
-
-@item 
-Objects that take too much storage
-
-@item 
-Unchecked conversion between types of differing sizes
-
-@item 
-Missing @code{return} statement along some execution path in a function
-
-@item 
-Incorrect (unrecognized) pragmas
-
-@item 
-Incorrect external names
-
-@item 
-Allocation from empty storage pool
-
-@item 
-Potentially blocking operation in protected type
-
-@item 
-Suspicious parenthesization of expressions
-
-@item 
-Mismatching bounds in an aggregate
-
-@item 
-Attempt to return local value by reference
-
-@item 
-Premature instantiation of a generic body
-
-@item 
-Attempt to pack aliased components
-
-@item 
-Out of bounds array subscripts
-
-@item 
-Wrong length on string assignment
-
-@item 
-Violations of style rules if style checking is enabled
-
-@item 
-Unused `with' clauses
-
-@item 
-@code{Bit_Order} usage that does not have any effect
-
-@item 
-@code{Standard.Duration} used to resolve universal fixed expression
-
-@item 
-Dereference of possibly null value
-
-@item 
-Declaration that is likely to cause storage error
-
-@item 
-Internal GNAT unit `with'ed by application unit
-
-@item 
-Values known to be out of range at compile time
-
-@item 
-Unreferenced or unmodified variables. Note that a special
-exemption applies to variables which contain any of the substrings
-@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.
-
-@item 
-Address overlays that could clobber memory
-
-@item 
-Unexpected initialization when address clause present
-
-@item 
-Bad alignment for address clause
-
-@item 
-Useless type conversions
-
-@item 
-Redundant assignment statements and other redundant constructs
-
-@item 
-Useless exception handlers
-
-@item 
-Accidental hiding of name by child unit
-
-@item 
-Access before elaboration detected at compile time
-
-@item 
-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
-to control the handling of warning messages. It is also possible
-to exercise much finer control over what warnings are issued and
-suppressed using the GNAT pragma Warnings (see the description
-of the pragma in the @cite{GNAT_Reference_manual}).
-
-@geindex -gnatwa (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwa}
-
-`Activate most optional warnings.'
-
-This switch activates most optional warning messages. See the remaining list
-in this section for details on optional warning messages that can be
-individually controlled.  The warnings that are not turned on by this
-switch are:
-
-
-@itemize *
-
-@item 
-@code{-gnatwd} (implicit dereferencing)
-
-@item 
-@code{-gnatw.d} (tag warnings with -gnatw switch)
-
-@item 
-@code{-gnatwh} (hiding)
-
-@item 
-@code{-gnatw.h} (holes in record layouts)
-
-@item 
-@code{-gnatw.j} (late primitives of tagged types)
-
-@item 
-@code{-gnatw.k} (redefinition of names in standard)
-
-@item 
-@code{-gnatwl} (elaboration warnings)
-
-@item 
-@code{-gnatw.l} (inherited aspects)
-
-@item 
-@code{-gnatw.n} (atomic synchronization)
-
-@item 
-@code{-gnatwo} (address clause overlay)
-
-@item 
-@code{-gnatw.o} (values set by out parameters ignored)
-
-@item 
-@code{-gnatw.q} (questionable layout of record types)
-
-@item 
-@code{-gnatw_q} (ignored equality)
-
-@item 
-@code{-gnatw_r} (out-of-order record representation clauses)
-
-@item 
-@code{-gnatw.s} (overridden size clause)
-
-@item 
-@code{-gnatwt} (tracking of deleted conditional code)
-
-@item 
-@code{-gnatw.u} (unordered enumeration)
-
-@item 
-@code{-gnatw.w} (use of Warnings Off)
-
-@item 
-@code{-gnatw.y} (reasons for package needing body)
-@end itemize
-
-All other optional warnings are turned on.
-@end table
-
-@geindex -gnatwA (gcc)
-
-
-@table @asis
-
-@item @code{-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 @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 @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
-
-@geindex -gnatw.a (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.a}
-
-`Activate warnings on failing assertions.'
-
-@geindex Assert failures
-
-This switch activates warnings for assertions where the compiler can tell at
-compile time that the assertion will fail. Note that this warning is given
-even if assertions are disabled. The default is that such warnings are
-generated.
-@end table
-
-@geindex -gnatw.A (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.A}
-
-`Suppress warnings on failing assertions.'
-
-@geindex Assert failures
-
-This switch suppresses warnings for assertions where the compiler can tell at
-compile time that the assertion will fail.
-@end table
-
-@geindex -gnatw_a
-
-
-@table @asis
-
-@item @code{-gnatw_a}
-
-`Activate warnings on anonymous allocators.'
-
-@geindex Anonymous allocators
-
-This switch activates warnings for allocators of anonymous access types,
-which can involve run-time accessibility checks and lead to unexpected
-accessibility violations. For more details on the rules involved, see
-RM 3.10.2 (14).
-@end table
-
-@geindex -gnatw_A
-
-
-@table @asis
-
-@item @code{-gnatw_A}
-
-`Supress warnings on anonymous allocators.'
-
-@geindex Anonymous allocators
-
-This switch suppresses warnings for anonymous access type allocators.
-@end table
-
-@geindex -gnatwb (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwb}
-
-`Activate warnings on bad fixed values.'
-
-@geindex Bad fixed values
-
-@geindex Fixed-point Small value
-
-@geindex Small value
-
-This switch activates warnings for static fixed-point expressions whose
-value is not an exact multiple of Small. Such values are implementation
-dependent, since an implementation is free to choose either of the multiples
-that surround the value. GNAT always chooses the closer one, but this is not
-required behavior, and it is better to specify a value that is an exact
-multiple, ensuring predictable execution. The default is that such warnings
-are not generated.
-@end table
-
-@geindex -gnatwB (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwB}
-
-`Suppress warnings on bad fixed values.'
-
-This switch suppresses warnings for static fixed-point expressions whose
-value is not an exact multiple of Small.
-@end table
-
-@geindex -gnatw.b (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.b}
-
-`Activate warnings on biased representation.'
-
-@geindex Biased representation
-
-This switch activates warnings when a size clause, value size clause, component
-clause, or component size clause forces the use of biased representation for an
-integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
-to represent 10/11). The default is that such warnings are generated.
-@end table
-
-@geindex -gnatwB (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.B}
-
-`Suppress warnings on biased representation.'
-
-This switch suppresses warnings for representation clauses that force the use
-of biased representation.
-@end table
-
-@geindex -gnatwc (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwc}
-
-`Activate warnings on conditionals.'
-
-@geindex Conditionals
-@geindex constant
-
-This switch activates warnings for conditional expressions used in
-tests that are known to be True or False at compile time. The default
-is that such warnings are not generated.
-Note that this warning does
-not get issued for the use of boolean constants whose
-values are known at compile time, since this is a standard technique
-for conditional compilation in Ada, and this would generate too many
-false positive warnings.
-
-This warning option also activates a special test for comparisons using
-the operators ‘>=’ and’ <=’.
-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 @code{Natural} variable <= 0.
-
-This warning option also generates warnings if
-one or both tests is optimized away in a membership test for integer
-values if the result can be determined at compile time. Range tests on
-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 @code{-gnatwa}.
-@end table
-
-@geindex -gnatwC (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwC}
-
-`Suppress warnings on conditionals.'
-
-This switch suppresses warnings for conditional expressions used in
-tests that are known to be True or False at compile time.
-@end table
-
-@geindex -gnatw.c (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.c}
-
-`Activate warnings on missing component clauses.'
-
-@geindex Component clause
-@geindex missing
-
-This switch activates warnings for record components where a record
-representation clause is present and has component clauses for the
-majority, but not all, of the components. A warning is given for each
-component for which no component clause is present.
-@end table
-
-@geindex -gnatw.C (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.C}
-
-`Suppress warnings on missing component clauses.'
-
-This switch suppresses warnings for record components that are
-missing a component clause in the situation described above.
-@end table
-
-@geindex -gnatw_c (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw_c}
-
-`Activate warnings on unknown condition in Compile_Time_Warning.'
-
-@geindex Compile_Time_Warning
-
-@geindex Compile_Time_Error
-
-This switch activates warnings on a pragma Compile_Time_Warning
-or Compile_Time_Error whose condition has a value that is not
-known at compile time.
-The default is that such warnings are generated.
-@end table
-
-@geindex -gnatw_C (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw_C}
-
-`Suppress warnings on unknown condition in Compile_Time_Warning.'
-
-This switch supresses warnings on a pragma Compile_Time_Warning
-or Compile_Time_Error whose condition has a value that is not
-known at compile time.
-@end table
-
-@geindex -gnatwd (gcc)
-
-
-@table @asis
-
-@item @code{-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 @code{.all} will generate a warning. With this warning
-enabled, access checks occur only at points where an explicit
-@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
-
-@geindex -gnatwD (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwD}
-
-`Suppress warnings on implicit dereferencing.'
-
-@geindex Implicit dereferencing
-
-@geindex Dereferencing
-@geindex implicit
-
-This switch suppresses warnings for implicit dereferences in
-indexed components, slices, and selected components.
-@end table
-
-@geindex -gnatw.d (gcc)
-
-
-@table @asis
-
-@item @code{-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:
-
-@quotation
-
-
-@itemize -
-
-@item 
-`[-gnatw?]'
-Used to tag warnings controlled by the switch @code{-gnatwx} where x
-is a letter a-z.
-
-@item 
-`[-gnatw.?]'
-Used to tag warnings controlled by the switch @code{-gnatw.x} where x
-is a letter a-z.
-
-@item 
-`[-gnatel]'
-Used to tag elaboration information (info) messages generated when the
-static model of elaboration is used and the @code{-gnatel} switch is set.
-
-@item 
-`[restriction warning]'
-Used to tag warning messages for restriction violations, activated by use
-of the pragma @code{Restriction_Warnings}.
-
-@item 
-`[warning-as-error]'
-Used to tag warning messages that have been converted to error messages by
-use of the pragma Warning_As_Error. Note that such warnings are prefixed by
-the string “error: “ rather than “warning: “.
-
-@item 
-`[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 @code{-gnatws}.
-@end itemize
-@end quotation
-@end table
-
-@geindex -gnatw.d (gcc)
-
-
-@table @asis
-
-@item @code{-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
-@code{-gnatw.d}.
-@end table
-
-@geindex -gnatwe (gcc)
-
-@geindex Warnings
-@geindex treat as error
-
-
-@table @asis
-
-@item @code{-gnatwe}
-
-`Treat warnings and style checks as errors.'
-
-This switch causes warning messages and style check messages 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. Note that this
-is the only -gnatw switch that affects the handling of style check messages.
-Note also that this switch has no effect on info (information) messages, which
-are not treated as errors if this switch is present.
-@end table
-
-@geindex -gnatw.e (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.e}
-
-`Activate every optional warning.'
-
-@geindex Warnings
-@geindex activate every optional warning
-
-This switch activates all optional warnings, including those which
-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 @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}
-
-`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)
-
-
-@table @asis
-
-@item @code{-gnatwf}
-
-`Activate warnings on unreferenced formals.'
-
-@geindex Formals
-@geindex 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 @code{-gnatwu}. The
-default is that these warnings are not generated.
-@end table
-
-@geindex -gnatwF (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwF}
-
-`Suppress warnings on unreferenced formals.'
-
-This switch suppresses warnings for unreferenced formal
-parameters. Note that the
-combination @code{-gnatwu} followed by @code{-gnatwF} has the
-effect of warning on unreferenced entities other than subprogram
-formals.
-@end table
-
-@geindex -gnatwg (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwg}
-
-`Activate warnings on unrecognized pragmas.'
-
-@geindex Pragmas
-@geindex unrecognized
-
-This switch causes a warning to be generated if an unrecognized
-pragma is encountered. Apart from issuing this warning, the
-pragma is ignored and has no effect. The default
-is that such warnings are issued (satisfying the Ada Reference
-Manual requirement that such warnings appear).
-@end table
-
-@geindex -gnatwG (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwG}
-
-`Suppress warnings on unrecognized pragmas.'
-
-This switch suppresses warnings for unrecognized pragmas.
-@end table
-
-@geindex -gnatw.g (gcc)
-
-
-@table @asis
-
-@item @code{-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
-@code{-gnatwAao.q.s.CI.V.X.Z}
-but more warnings may be added in the future without advanced notice.
-@end table
-
-@geindex -gnatwh (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwh}
-
-`Activate warnings on hiding.'
-
-@geindex Hiding of Declarations
-
-This switch activates warnings on hiding declarations that are considered
-potentially confusing. Not all cases of hiding cause warnings; for example an
-overriding declaration hides an implicit declaration, which is just normal
-code. The default is that warnings on hiding are not generated.
-@end table
-
-@geindex -gnatwH (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwH}
-
-`Suppress warnings on hiding.'
-
-This switch suppresses warnings on hiding declarations.
-@end table
-
-@geindex -gnatw.h (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.h}
-
-`Activate warnings on holes/gaps in records.'
-
-@geindex Record Representation (gaps)
-
-This switch activates warnings on component clauses in record
-representation clauses that leave holes (gaps) in the record layout.
-If this warning option is active, then record representation clauses
-should specify a contiguous layout, adding unused fill fields if needed.
-@end table
-
-@geindex -gnatw.H (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.H}
-
-`Suppress warnings on holes/gaps in records.'
-
-This switch suppresses warnings on component clauses in record
-representation clauses that leave holes (haps) in the record layout.
-@end table
-
-@geindex -gnatwi (gcc)
-
-
-@table @asis
-
-@item @code{-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 @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
-for internal implementation purposes and should not be `with'ed
-by user programs. The default is that such warnings are generated
-@end table
-
-@geindex -gnatwI (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwI}
-
-`Disable warnings on implementation units.'
-
-This switch disables warnings for a `with' of an internal GNAT
-implementation unit.
-@end table
-
-@geindex -gnatw.i (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.i}
-
-`Activate warnings on overlapping actuals.'
-
-This switch enables a warning on statically detectable overlapping actuals in
-a subprogram call, when one of the actuals is an in-out parameter, and the
-types of the actuals are not by-copy types. This warning is off by default.
-@end table
-
-@geindex -gnatw.I (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.I}
-
-`Disable warnings on overlapping actuals.'
-
-This switch disables warnings on overlapping actuals in a call.
-@end table
-
-@geindex -gnatwj (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwj}
-
-`Activate warnings on obsolescent features (Annex J).'
-
-@geindex Features
-@geindex obsolescent
-
-@geindex Obsolescent features
-
-If this warning option is activated, then warnings are generated for
-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, uses 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, @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 @code{No_Obsolescent_Features} in two respects.
-First, the restriction applies only to annex J features.
-Second, the restriction does flag uses of package @code{ASCII}.
-@end table
-
-@geindex -gnatwJ (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwJ}
-
-`Suppress warnings on obsolescent features (Annex J).'
-
-This switch disables warnings on use of obsolescent features.
-@end table
-
-@geindex -gnatw.j (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.j}
-
-`Activate warnings on late declarations of tagged type primitives.'
-
-This switch activates warnings on visible primitives added to a
-tagged type after deriving a private extension from it.
-@end table
-
-@geindex -gnatw.J (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.J}
-
-`Suppress warnings on late declarations of tagged type primitives.'
-
-This switch suppresses warnings on visible primitives added to a
-tagged type after deriving a private extension from it.
-@end table
-
-@geindex -gnatwk (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwk}
-
-`Activate warnings on variables that could be constants.'
-
-This switch activates warnings for variables that are initialized but
-never modified, and then could be declared constants. The default is that
-such warnings are not given.
-@end table
-
-@geindex -gnatwK (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwK}
-
-`Suppress warnings on variables that could be constants.'
-
-This switch disables warnings on variables that could be declared constants.
-@end table
-
-@geindex -gnatw.k (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.k}
-
-`Activate warnings on redefinition of names in standard.'
-
-This switch activates warnings for declarations that declare a name that
-is defined in package Standard. Such declarations can be confusing,
-especially since the names in package Standard continue to be directly
-visible, meaning that use visibiliy on such redeclared names does not
-work as expected. Names of discriminants and components in records are
-not included in this check.
-@end table
-
-@geindex -gnatwK (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.K}
-
-`Suppress warnings on redefinition of names in standard.'
-
-This switch disables warnings for declarations that declare a name that
-is defined in package Standard.
-@end table
-
-@geindex -gnatwl (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwl}
-
-`Activate warnings for elaboration pragmas.'
-
-@geindex Elaboration
-@geindex warnings
-
-This switch activates warnings for possible elaboration problems,
-including suspicious use
-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
-are not generated.
-@end table
-
-@geindex -gnatwL (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwL}
-
-`Suppress warnings for elaboration pragmas.'
-
-This switch suppresses warnings for possible elaboration problems.
-@end table
-
-@geindex -gnatw.l (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.l}
-
-`List inherited aspects.'
-
-This switch causes the compiler to list inherited invariants,
-preconditions, and postconditions from Type_Invariant’Class, Invariant’Class,
-Pre’Class, and Post’Class aspects. Also list inherited subtype predicates.
-@end table
-
-@geindex -gnatw.L (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.L}
-
-`Suppress listing of inherited aspects.'
-
-This switch suppresses listing of inherited aspects.
-@end table
-
-@geindex -gnatwm (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwm}
-
-`Activate warnings on modified but unreferenced variables.'
-
-This switch activates warnings for variables that are assigned (using
-an initialization value or with one or more assignment statements) but
-whose value is never read. The warning is suppressed for volatile
-variables and also for variables that are renamings of other variables
-or for which an address clause is given.
-The default is that these warnings are not given.
-@end table
-
-@geindex -gnatwM (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwM}
-
-`Disable warnings on modified but unreferenced variables.'
-
-This switch disables warnings for variables that are assigned or
-initialized, but never read.
-@end table
-
-@geindex -gnatw.m (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.m}
-
-`Activate warnings on suspicious modulus values.'
-
-This switch activates warnings for modulus values that seem suspicious.
-The cases caught are where the size is the same as the modulus (e.g.
-a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64
-with no size clause. The guess in both cases is that 2**x was intended
-rather than x. In addition expressions of the form 2*x for small x
-generate a warning (the almost certainly accurate guess being that
-2**x was intended). This switch also activates warnings for negative
-literal values of a modular type, which are interpreted as large positive
-integers after wrap-around. The default is that these warnings are given.
-@end table
-
-@geindex -gnatw.M (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.M}
-
-`Disable warnings on suspicious modulus values.'
-
-This switch disables warnings for suspicious modulus values.
-@end table
-
-@geindex -gnatwn (gcc)
-
-
-@table @asis
-
-@item @code{-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 @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)
-
-@geindex Atomic Synchronization
-@geindex warnings
-
-
-@table @asis
-
-@item @code{-gnatw.n}
-
-`Activate warnings on atomic synchronization.'
-
-This switch actives warnings when an access to an atomic variable
-requires the generation of atomic synchronization code. These
-warnings are off by default.
-@end table
-
-@geindex -gnatw.N (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.N}
-
-`Suppress warnings on atomic synchronization.'
-
-@geindex Atomic Synchronization
-@geindex warnings
-
-This switch suppresses warnings when an access to an atomic variable
-requires the generation of atomic synchronization code.
-@end table
-
-@geindex -gnatwo (gcc)
-
-@geindex Address Clauses
-@geindex warnings
-
-
-@table @asis
-
-@item @code{-gnatwo}
-
-`Activate warnings on address clause overlays.'
-
-This switch activates warnings for possibly unintended initialization
-effects of defining address clauses that cause one variable to overlap
-another. The default is that such warnings are generated.
-@end table
-
-@geindex -gnatwO (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwO}
-
-`Suppress warnings on address clause overlays.'
-
-This switch suppresses warnings on possibly unintended initialization
-effects of defining address clauses that cause one variable to overlap
-another.
-@end table
-
-@geindex -gnatw.o (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.o}
-
-`Activate warnings on modified but unreferenced out parameters.'
-
-This switch activates warnings for variables that are modified by using
-them as actuals for a call to a procedure with an out mode formal, where
-the resulting assigned value is never read. It is applicable in the case
-where there is more than one out mode formal. If there is only one out
-mode formal, the warning is issued by default (controlled by -gnatwu).
-The warning is suppressed for volatile
-variables and also for variables that are renamings of other variables
-or for which an address clause is given.
-The default is that these warnings are not given.
-@end table
-
-@geindex -gnatw.O (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.O}
-
-`Disable warnings on modified but unreferenced out parameters.'
-
-This switch suppresses warnings for variables that are modified by using
-them as actuals for a call to a procedure with an out mode formal, where
-the resulting assigned value is never read.
-@end table
-
-@geindex -gnatwp (gcc)
-
-@geindex Inlining
-@geindex warnings
-
-
-@table @asis
-
-@item @code{-gnatwp}
-
-`Activate warnings on ineffective pragma Inlines.'
-
-This switch activates warnings for failure of front end inlining
-(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.
-Warnings on ineffective inlining by the gcc back-end can be activated
-separately, using the gcc switch -Winline.
-@end table
-
-@geindex -gnatwP (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwP}
-
-`Suppress warnings on ineffective pragma Inlines.'
-
-This switch suppresses warnings on ineffective pragma Inlines. If the
-inlining mechanism cannot inline a call, it will simply ignore the
-request silently.
-@end table
-
-@geindex -gnatw.p (gcc)
-
-@geindex Parameter order
-@geindex warnings
-
-
-@table @asis
-
-@item @code{-gnatw.p}
-
-`Activate warnings on parameter ordering.'
-
-This switch activates warnings for cases of suspicious parameter
-ordering when the list of arguments are all simple identifiers that
-match the names of the formals, but are in a different order. The
-warning is suppressed if any use of named parameter notation is used,
-so this is the appropriate way to suppress a false positive (and
-serves to emphasize that the “misordering” is deliberate). The
-default is that such warnings are not given.
-@end table
-
-@geindex -gnatw.P (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.P}
-
-`Suppress warnings on parameter ordering.'
-
-This switch suppresses warnings on cases of suspicious parameter
-ordering.
-@end table
-
-@geindex -gnatw_p (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw_p}
-
-`Activate warnings for pedantic checks.'
-
-This switch activates warnings for the failure of certain pedantic checks.
-The only case currently supported is a check that the subtype_marks given
-for corresponding formal parameter and function results in a subprogram
-declaration and its body denote the same subtype declaration. The default
-is that such warnings are not given.
-@end table
-
-@geindex -gnatw_P (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw_P}
-
-`Suppress warnings for pedantic checks.'
-
-This switch suppresses warnings on violations of pedantic checks.
-@end table
-
-@geindex -gnatwq (gcc)
-
-@geindex Parentheses
-@geindex warnings
-
-
-@table @asis
-
-@item @code{-gnatwq}
-
-`Activate warnings on questionable missing parentheses.'
-
-This switch activates warnings for cases where parentheses are not used and
-the result is potential ambiguity from a readers point of view. For example
-(not a > b) when a and b are modular means ((not a) > b) and very likely the
-programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and
-quite likely ((-x) mod 5) was intended. In such situations it seems best to
-follow the rule of always parenthesizing to make the association clear, and
-this warning switch warns if such parentheses are not present. The default
-is that these warnings are given.
-@end table
-
-@geindex -gnatwQ (gcc)
-
-
-@table @asis
-
-@item @code{-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.
-@end table
-
-@geindex -gnatw.q (gcc)
-
-@geindex Layout
-@geindex warnings
-
-
-@table @asis
-
-@item @code{-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:
-
-
-@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}
-
-`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 -gnatw_q (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw_q}
-
-`Activate warnings for ignored equality operators.'
-
-This switch activates warnings for a user-defined “=” function that does
-not compose (i.e. is ignored for a predefined “=” for a composite type
-containing a component whose type has the user-defined “=” as
-primitive). Note that the user-defined “=” must be a primitive operator
-in order to trigger the warning.
-
-The default is that these warnings are not given.
-@end table
-
-@geindex -gnatw_Q (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw_Q}
-
-`Suppress warnings for ignored equality operators.'
-@end table
-
-@geindex -gnatwr (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwr}
-
-`Activate warnings on redundant constructs.'
-
-This switch activates warnings for redundant constructs. The following
-is the current list of constructs regarded as redundant:
-
-
-@itemize *
-
-@item 
-Assignment of an item to itself.
-
-@item 
-Type conversion that converts an expression to its own type.
-
-@item 
-Use of the attribute @code{Base} where @code{typ'Base} is the same
-as @code{typ}.
-
-@item 
-Use of pragma @code{Pack} when all components are placed by a record
-representation clause.
-
-@item 
-Exception handler containing only a reraise statement (raise with no
-operand) which has no effect.
-
-@item 
-Use of the operator abs on an operand that is known at compile time
-to be non-negative
-
-@item 
-Comparison of an object or (unary or binary) operation of boolean type to
-an explicit True value.
-
-@item 
-Import of parent package.
-@end itemize
-
-The default is that warnings for redundant constructs are not given.
-@end table
-
-@geindex -gnatwR (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwR}
-
-`Suppress warnings on redundant constructs.'
-
-This switch suppresses warnings for redundant constructs.
-@end table
-
-@geindex -gnatw.r (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.r}
-
-`Activate warnings for object renaming function.'
-
-This switch activates warnings for an object renaming that renames a
-function call, which is equivalent to a constant declaration (as
-opposed to renaming the function itself).  The default is that these
-warnings are given.
-@end table
-
-@geindex -gnatw.R (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.R}
-
-`Suppress warnings for object renaming function.'
-
-This switch suppresses warnings for object renaming function.
-@end table
-
-@geindex -gnatw_r (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw_r}
-
-`Activate warnings for out-of-order record representation clauses.'
-
-This switch activates warnings for record representation clauses,
-if the order of component declarations, component clauses,
-and bit-level layout do not all agree.
-The default is that these warnings are not given.
-@end table
-
-@geindex -gnatw_R (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw_R}
-
-`Suppress warnings for out-of-order record representation clauses.'
-@end table
-
-@geindex -gnatws (gcc)
-
-
-@table @asis
-
-@item @code{-gnatws}
-
-`Suppress all warnings.'
-
-This switch completely suppresses the
-output of all warning messages from the GNAT front end, including
-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 @code{-gnatwn}.
-
-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
-
-@geindex -gnatw.s (gcc)
-
-@geindex Record Representation (component sizes)
-
-
-@table @asis
-
-@item @code{-gnatw.s}
-
-`Activate warnings on overridden size clauses.'
-
-This switch activates warnings on component clauses in record
-representation clauses where the length given overrides that
-specified by an explicit size clause for the component type. A
-warning is similarly given in the array case if a specified
-component size overrides an explicit size clause for the array
-component type.
-@end table
-
-@geindex -gnatw.S (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.S}
-
-`Suppress warnings on overridden size clauses.'
-
-This switch suppresses warnings on component clauses in record
-representation clauses that override size clauses, and similar
-warnings when an array component size overrides a size clause.
-@end table
-
-@geindex -gnatwt (gcc)
-
-@geindex Deactivated code
-@geindex warnings
-
-@geindex Deleted code
-@geindex warnings
-
-
-@table @asis
-
-@item @code{-gnatwt}
-
-`Activate warnings for tracking of deleted conditional code.'
-
-This switch activates warnings for tracking of code in conditionals (IF and
-CASE statements) that is detected to be dead code which cannot be executed, and
-which is removed by the front end. This warning is off by default. This may be
-useful for detecting deactivated code in certified applications.
-@end table
-
-@geindex -gnatwT (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwT}
-
-`Suppress warnings for tracking of deleted conditional code.'
-
-This switch suppresses warnings for tracking of deleted conditional code.
-@end table
-
-@geindex -gnatw.t (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.t}
-
-`Activate warnings on suspicious contracts.'
-
-This switch activates warnings on suspicious contracts. This includes
-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
-it should rather be expressed as a precondition. This switch also controls
-warnings on suspicious cases of expressions typically found in contracts like
-quantified expressions and uses of Update attribute. The default is that such
-warnings are generated.
-@end table
-
-@geindex -gnatw.T (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.T}
-
-`Suppress warnings on suspicious contracts.'
-
-This switch suppresses warnings on suspicious contracts.
-@end table
-
-@geindex -gnatwu (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwu}
-
-`Activate warnings on unused entities.'
-
-This switch activates warnings to be generated for entities that
-are declared but not referenced, and for units that are `with'ed
-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 @code{use}
-clauses or @code{renames}
-declarations, a warning is still generated. A warning is also generated
-for a generic package that is `with'ed but never instantiated.
-In the case where a package or subprogram body is compiled, and there
-is a `with' on the corresponding spec
-that is only referenced in the body,
-a warning is also generated, noting that the
-`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 @code{-gnatwf}).
-@end table
-
-@geindex -gnatwU (gcc)
-
-
-@table @asis
-
-@item @code{-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 @code{-gnatwF}).
-@end table
-
-@geindex -gnatw.u (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.u}
-
-`Activate warnings on unordered enumeration types.'
-
-This switch causes enumeration types to be considered as conceptually
-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 `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 @code{Ordered} in the
-@cite{GNAT Reference Manual} for further details.
-The default is that such warnings are not generated.
-@end table
-
-@geindex -gnatw.U (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.U}
-
-`Deactivate warnings on unordered enumeration types.'
-
-This switch causes all enumeration types to be considered as ordered, so
-that no warnings are given for comparisons or subranges for any type.
-@end table
-
-@geindex -gnatwv (gcc)
-
-@geindex Unassigned variable warnings
-
-
-@table @asis
-
-@item @code{-gnatwv}
-
-`Activate warnings on unassigned variables.'
-
-This switch activates warnings for access to variables which
-may not be properly initialized. The default is that
-such warnings are generated. This switch will also be emitted when
-initializing an array or record object via the following aggregate:
-
-@example
-Array_Or_Record : XXX := (others => <>);
-@end example
-
-unless the relevant type fully initializes all components.
-@end table
-
-@geindex -gnatwV (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwV}
-
-`Suppress warnings on unassigned variables.'
-
-This switch suppresses warnings for access to variables which
-may not be properly initialized.
-@end table
-
-@geindex -gnatw.v (gcc)
-
-@geindex bit order warnings
-
-
-@table @asis
-
-@item @code{-gnatw.v}
-
-`Activate info messages for non-default bit order.'
-
-This switch activates messages (labeled “info”, they are not warnings,
-just informational messages) about the effects of non-default bit-order
-on records to which a component clause is applied. The effect of specifying
-non-default bit ordering is a bit subtle (and changed with Ada 2005), so
-these messages, which are given by default, are useful in understanding the
-exact consequences of using this feature.
-@end table
-
-@geindex -gnatw.V (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.V}
-
-`Suppress info messages for non-default bit order.'
-
-This switch suppresses information messages for the effects of specifying
-non-default bit order on record components with component clauses.
-@end table
-
-@geindex -gnatww (gcc)
-
-@geindex String indexing warnings
-
-
-@table @asis
-
-@item @code{-gnatww}
-
-`Activate warnings on wrong low bound assumption.'
-
-This switch activates warnings for indexing an unconstrained string parameter
-with a literal or S’Length. This is a case where the code is assuming that the
-low bound is one, which is in general not true (for example when a slice is
-passed). The default is that such warnings are generated.
-@end table
-
-@geindex -gnatwW (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwW}
-
-`Suppress warnings on wrong low bound assumption.'
-
-This switch suppresses warnings for indexing an unconstrained string parameter
-with a literal or S’Length. Note that this warning can also be suppressed
-in a particular case by adding an assertion that the lower bound is 1,
-as shown in the following example:
-
-@example
-procedure K (S : String) is
-   pragma Assert (S'First = 1);
-   ...
-@end example
-@end table
-
-@geindex -gnatw.w (gcc)
-
-@geindex Warnings Off control
-
-
-@table @asis
-
-@item @code{-gnatw.w}
-
-`Activate warnings on Warnings Off pragmas.'
-
-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 @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.
-The default is that these warnings are not given.
-@end table
-
-@geindex -gnatw.W (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.W}
-
-`Suppress warnings on unnecessary Warnings Off pragmas.'
-
-This switch suppresses warnings for use of @code{pragma Warnings (Off, ...)}.
-@end table
-
-@geindex -gnatwx (gcc)
-
-@geindex Export/Import pragma warnings
-
-
-@table @asis
-
-@item @code{-gnatwx}
-
-`Activate warnings on Export/Import pragmas.'
-
-This switch activates warnings on Export/Import pragmas when
-the compiler detects a possible conflict between the Ada and
-foreign language calling sequences. For example, the use of
-default parameters in a convention C procedure is dubious
-because the C compiler cannot supply the proper default, so
-a warning is issued. The default is that such warnings are
-generated.
-@end table
-
-@geindex -gnatwX (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwX}
-
-`Suppress warnings on Export/Import pragmas.'
-
-This switch suppresses warnings on Export/Import pragmas.
-The sense of this is that you are telling the compiler that
-you know what you are doing in writing the pragma, and it
-should not complain at you.
-@end table
-
-@geindex -gnatwm (gcc)
-
-
-@table @asis
-
-@item @code{-gnatw.x}
-
-`Activate warnings for No_Exception_Propagation mode.'
-
-This switch activates warnings for exception usage when pragma Restrictions
-(No_Exception_Propagation) is in effect. Warnings are given for implicit or
-explicit exception raises which are not covered by a local handler, and for
-exception handlers which do not cover a local raise. The default is that
-these warnings are given for units that contain exception handlers.
-
-@item @code{-gnatw.X}
-
-`Disable warnings for No_Exception_Propagation mode.'
-
-This switch disables warnings for exception usage when pragma Restrictions
-(No_Exception_Propagation) is in effect.
-@end table
-
-@geindex -gnatwy (gcc)
-
-@geindex Ada compatibility issues warnings
-
-
-@table @asis
-
-@item @code{-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
-@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
-was called Ada 0Y, hence the choice of character.
-@end table
-
-@geindex -gnatwY (gcc)
-
-@geindex Ada compatibility issues warnings
-
-
-@table @asis
-
-@item @code{-gnatwY}
-
-`Disable warnings for Ada compatibility issues.'
-
-This switch suppresses the warnings intended to help in identifying
-incompatibilities between Ada language versions.
-@end table
-
-@geindex -gnatw.y (gcc)
-
-@geindex Package spec needing body
-
-
-@table @asis
-
-@item @code{-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.
-For example, the use of pragma Elaborate_Body, or the declaration
-of a procedure specification requiring a completion. This switch
-causes information messages to be output showing why a package
-specification requires a body. This can be useful in the case of
-a large package specification which is unexpectedly requiring a
-body. The default is that such information messages are not output.
-@end table
-
-@geindex -gnatw.Y (gcc)
-
-@geindex No information messages for why package spec needs body
-
-
-@table @asis
-
-@item @code{-gnatw.Y}
-
-`Disable information messages for why package spec needs body.'
-
-This switch suppresses the output of information messages showing why
-a package specification needs a body.
-@end table
-
-@geindex -gnatwz (gcc)
-
-@geindex Unchecked_Conversion warnings
-
-
-@table @asis
-
-@item @code{-gnatwz}
-
-`Activate warnings on unchecked conversions.'
-
-This switch activates warnings for unchecked conversions
-where the types are known at compile time to have different
-sizes. The default is that such warnings are generated. Warnings are also
-generated for subprogram pointers with different conventions.
-@end table
-
-@geindex -gnatwZ (gcc)
-
-
-@table @asis
-
-@item @code{-gnatwZ}
-
-`Suppress warnings on unchecked conversions.'
-
-This switch suppresses warnings for unchecked conversions
-where the types are known at compile time to have different
-sizes or conventions.
-@end table
-
-@geindex -gnatw.z (gcc)
-
-@geindex Size/Alignment warnings
-
-
-@table @asis
-
-@item @code{-gnatw.z}
-
-`Activate warnings for size not a multiple of alignment.'
-
-This switch activates warnings for cases of array and record types
-with 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.
-@end table
-
-@geindex -gnatw.Z (gcc)
-
-@geindex Size/Alignment warnings
-
-
-@table @asis
-
-@item @code{-gnatw.Z}
-
-`Suppress warnings for size not a multiple of alignment.'
-
-This switch suppresses warnings for cases of array and record types
-with 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 @code{Object_Size} value.
-@end table
-
-@geindex -Wunused (gcc)
-
-
-@table @asis
-
-@item @code{-Wunused}
-
-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
-
-@geindex -Wuninitialized (gcc)
-
-
-@table @asis
-
-@item @code{-Wuninitialized}
-
-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
-
-@geindex -Wstack-usage (gcc)
-
-
-@table @asis
-
-@item @code{-Wstack-usage=`len'}
-
-Warn if the stack usage of a subprogram might be larger than @code{len} bytes.
-See @ref{e6,,Static Stack Usage Analysis} for details.
-@end table
-
-@geindex -Wall (gcc)
-
-
-@table @asis
-
-@item @code{-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.
-The use of this switch also sets the default front-end warning mode to
-@code{-gnatwa}, that is, most front-end warnings are activated as well.
-@end table
-
-@geindex -w (gcc)
-
-
-@table @asis
-
-@item @code{-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
-@code{-gnatws}, that is, front-end warnings are suppressed as well.
-@end table
-
-@geindex -Werror (gcc)
-
-
-@table @asis
-
-@item @code{-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.
-The use of this switch also sets the default front-end warning mode to
-@code{-gnatwe}, that is, front-end warning messages and style check
-messages are treated as errors as well.
-@end table
-
-A string of warning parameters can be used in the same parameter. For example:
-
-@example
--gnatwaGe
-@end example
-
-will turn on all optional warnings except for unrecognized pragma warnings,
-and also specify that warnings should be treated as errors.
-
-When no switch @code{-gnatw} is used, this is equivalent to:
-
-@quotation
-
-
-@itemize *
-
-@item 
-@code{-gnatw.a}
-
-@item 
-@code{-gnatwB}
-
-@item 
-@code{-gnatw.b}
-
-@item 
-@code{-gnatwC}
-
-@item 
-@code{-gnatw.C}
-
-@item 
-@code{-gnatwD}
-
-@item 
-@code{-gnatw.D}
-
-@item 
-@code{-gnatwF}
-
-@item 
-@code{-gnatw.F}
-
-@item 
-@code{-gnatwg}
-
-@item 
-@code{-gnatwH}
-
-@item 
-@code{-gnatw.H}
-
-@item 
-@code{-gnatwi}
-
-@item 
-@code{-gnatwJ}
-
-@item 
-@code{-gnatw.J}
-
-@item 
-@code{-gnatwK}
-
-@item 
-@code{-gnatw.K}
-
-@item 
-@code{-gnatwL}
-
-@item 
-@code{-gnatw.L}
-
-@item 
-@code{-gnatwM}
-
-@item 
-@code{-gnatw.m}
-
-@item 
-@code{-gnatwn}
-
-@item 
-@code{-gnatw.N}
-
-@item 
-@code{-gnatwo}
-
-@item 
-@code{-gnatw.O}
-
-@item 
-@code{-gnatwP}
-
-@item 
-@code{-gnatw.P}
-
-@item 
-@code{-gnatwq}
-
-@item 
-@code{-gnatw.Q}
-
-@item 
-@code{-gnatwR}
-
-@item 
-@code{-gnatw.R}
-
-@item 
-@code{-gnatw.S}
-
-@item 
-@code{-gnatwT}
-
-@item 
-@code{-gnatw.t}
-
-@item 
-@code{-gnatwU}
-
-@item 
-@code{-gnatw.U}
-
-@item 
-@code{-gnatwv}
-
-@item 
-@code{-gnatw.v}
-
-@item 
-@code{-gnatww}
-
-@item 
-@code{-gnatw.W}
-
-@item 
-@code{-gnatwx}
-
-@item 
-@code{-gnatw.X}
-
-@item 
-@code{-gnatwy}
-
-@item 
-@code{-gnatw.Y}
-
-@item 
-@code{-gnatwz}
-
-@item 
-@code{-gnatw.z}
-@end itemize
-@end quotation
-
-@node Debugging and Assertion Control,Validity Checking,Warning Message Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-and-assertion-control}@anchor{f1}@anchor{gnat_ugn/building_executable_programs_with_gnat id16}@anchor{f2}
-@subsection Debugging and Assertion Control
-
-
-@geindex -gnata (gcc)
-
-
-@table @asis
-
-@item @code{-gnata}
-
-@geindex Assert
-
-@geindex Debug
-
-@geindex Assertions
-
-@geindex Precondition
-
-@geindex Postcondition
-
-@geindex Type invariants
-
-@geindex Subtype predicates
-
-The @code{-gnata} option is equivalent to the following @code{Assertion_Policy} pragma:
-
-@example
-pragma Assertion_Policy (Check);
-@end example
-
-Which is a shorthand for:
-
-@example
-pragma Assertion_Policy
---  Ada RM assertion pragmas
-  (Assert                    => Check,
-   Static_Predicate          => Check,
-   Dynamic_Predicate         => Check,
-   Pre                       => Check,
-   Pre'Class                 => Check,
-   Post                      => Check,
-   Post'Class                => Check,
-   Type_Invariant            => Check,
-   Type_Invariant'Class      => Check,
-   Default_Initial_Condition => Check,
---  GNAT specific assertion pragmas
-   Assert_And_Cut            => Check,
-   Assume                    => Check,
-   Contract_Cases            => Check,
-   Debug                     => Check,
-   Ghost                     => Check,
-   Initial_Condition         => Check,
-   Loop_Invariant            => Check,
-   Loop_Variant              => Check,
-   Postcondition             => Check,
-   Precondition              => Check,
-   Predicate                 => Check,
-   Refined_Post              => Check,
-   Subprogram_Variant        => Check);
-@end example
-
-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.
-
-The pragmas have the form:
-
-@example
-pragma Assert (<Boolean-expression> [, <static-string-expression>])
-pragma Debug (<procedure call>)
-pragma Type_Invariant (<type-local-name>, <Boolean-expression>)
-pragma Predicate (<type-local-name>, <Boolean-expression>)
-pragma Precondition (<Boolean-expression>, <string-expression>)
-pragma Postcondition (<Boolean-expression>, <string-expression>)
-@end example
-
-The aspects have the form:
-
-@example
-with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate]
-  => <Boolean-expression>;
-@end example
-
-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
-@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 @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 @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
-@anchor{gnat_ugn/building_executable_programs_with_gnat id17}@anchor{f3}@anchor{gnat_ugn/building_executable_programs_with_gnat validity-checking}@anchor{e7}
-@subsection Validity Checking
-
-
-@geindex Validity Checking
-
-The Ada Reference Manual defines the concept of invalid values (see
-RM 13.9.1). The primary source of invalid values is uninitialized
-variables. A scalar variable that is left uninitialized may contain
-an invalid value; the concept of invalid does not apply to access or
-composite types.
-
-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 @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 @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
-not usually recommended for production builds, and in particular
-we do not recommend using these extra validity checking options in
-combination with optimization, since this can confuse the optimizer.
-If performance is a consideration, leading to the need to optimize,
-then the validity checking options should not be used.
-
-The other @code{-gnatV`x'} switches below allow finer-grained
-control; you can enable whichever validity checks you desire. However,
-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 @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 @code{-gnatV`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
-to the default checks required by Ada as described above.
-
-@geindex -gnatVa (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVa}
-
-`All validity checks.'
-
-All validity checks are turned on.
-That is, @code{-gnatVa} is
-equivalent to @code{gnatVcdefimoprst}.
-@end table
-
-@geindex -gnatVc (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVc}
-
-`Validity checks for copies.'
-
-The right-hand side of assignments, and the (explicit) initializing values
-of object declarations are validity checked.
-@end table
-
-@geindex -gnatVd (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVd}
-
-`Default (RM) validity checks.'
-
-Some validity checks are required by Ada (see RM 13.9.1 (9-11)); these
-(and only these) validity checks are enabled by default.
-For case statements (and case expressions) that lack a “when others =>”
-choice, a check is made that the value of the selector expression
-belongs to its nominal subtype. If it does not, Constraint_Error is raised.
-For assignments to array components (and for indexed components in some
-other contexts), a check is made that each index expression belongs to the
-corresponding index subtype. If it does not, Constraint_Error is raised.
-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.
-@end table
-
-@geindex -gnatVe (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVe}
-
-`Validity checks for scalar components.'
-
-In the absence of this switch, assignments to scalar components of
-enclosing record or array objects are not validity checked, even if
-validity checks for assignments generally (@code{-gnatVc}) are turned on.
-Specifying this switch enables such checks.
-This switch has no effect if the @code{-gnatVc} switch is not specified.
-@end table
-
-@geindex -gnatVf (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVf}
-
-`Validity checks for floating-point values.'
-
-Specifying this switch enables validity checking for floating-point
-values in the same contexts where validity checking is enabled for
-other scalar values.
-In the absence of this switch, validity checking is not performed for
-floating-point values. This takes precedence over other statements about
-performing validity checking for scalar objects in various scenarios.
-One way to look at it is that if this switch is not set, then whenever
-any of the other rules in this section use the word “scalar” they
-really mean “scalar and not floating-point”.
-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. The exact contexts
-in which floating-point values are checked depends on the setting of other
-options. For example, @code{-gnatVif} or @code{-gnatVfi}
-(the order does not matter) specifies that floating-point parameters of mode
-@code{in} should be validity checked.
-@end table
-
-@geindex -gnatVi (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVi}
-
-`Validity checks for `@w{`}in`@w{`} mode parameters.'
-
-Arguments for parameters of mode @code{in} are validity checked in function
-and procedure calls at the point of call.
-@end table
-
-@geindex -gnatVm (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVm}
-
-`Validity checks for `@w{`}in out`@w{`} mode parameters.'
-
-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 @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.
-@end table
-
-@geindex -gnatVn (gcc)
-
-
-@table @asis
-
-@item @code{-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 @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)
-
-
-@table @asis
-
-@item @code{-gnatVo}
-
-`Validity checks for operator and attribute operands.'
-
-Scalar arguments for predefined operators and for attributes are
-validity checked.
-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).
-@end table
-
-@geindex -gnatVp (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVp}
-
-`Validity checks for parameters.'
-
-This controls the treatment of formal parameters within a subprogram (as
-opposed to @code{-gnatVi} and @code{-gnatVm}, which control validity
-testing of actual parameters of a call). If either of these call options is
-specified, then normally an assumption is made within a subprogram that
-the validity of any incoming formal parameters of the corresponding mode(s)
-has already been checked at the point of call and does not need rechecking.
-If @code{-gnatVp} is set, then this assumption is not made and so their
-validity may be checked (or rechecked) within the subprogram. If neither of
-the two call-related options is specified, then this switch has no effect.
-@end table
-
-@geindex -gnatVr (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVr}
-
-`Validity checks for function returns.'
-
-The expression in simple @code{return} statements in functions is validity
-checked.
-@end table
-
-@geindex -gnatVs (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVs}
-
-`Validity checks for subscripts.'
-
-All subscript expressions are checked for validity, whatever context
-they occur in (in default mode some subscripts are not validity checked;
-for example, validity checking may be omitted in some cases involving
-a read of a component of an array).
-@end table
-
-@geindex -gnatVt (gcc)
-
-
-@table @asis
-
-@item @code{-gnatVt}
-
-`Validity checks for tests.'
-
-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 @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 @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 @code{in out} parameters.
-
-The specification of additional validity checking generates extra code (and
-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 @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 @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.
-
-@node Style Checking,Run-Time Checks,Validity Checking,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id18}@anchor{f4}@anchor{gnat_ugn/building_executable_programs_with_gnat style-checking}@anchor{ec}
-@subsection Style Checking
-
-
-@geindex Style checking
-
-@geindex -gnaty (gcc)
-
-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 @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
-style rules we have chosen for the GNAT sources. If you are starting
-a project which does not have established style standards, you may
-find it useful to adopt the entire set of GNAT coding standards, or
-some subset of them.
-
-
-The string @code{x} is a sequence of letters or digits
-indicating the particular style
-checks to be performed. The following checks are defined:
-
-@geindex -gnaty[0-9] (gcc)
-
-
-@table @asis
-
-@item @code{-gnaty0}
-
-`Specify indentation level.'
-
-If a digit from 1-9 appears
-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 rule checks that the following constructs start on a column that is
-a multiple of the alignment level:
-
-
-@itemize *
-
-@item 
-beginnings of declarations (except record component declarations)
-and statements;
-
-@item 
-beginnings of the structural components of compound statements;
-
-@item 
-@code{end} keyword that completes the declaration of a program unit declaration
-or body or that completes a compound statement.
-@end itemize
-
-Full line comments must be
-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
-non-blank line.
-@end table
-
-@geindex -gnatya (gcc)
-
-
-@table @asis
-
-@item @code{-gnatya}
-
-`Check attribute casing.'
-
-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.
-@end table
-
-@geindex -gnatyA (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyA}
-
-`Use of array index numbers in array attributes.'
-
-When using the array attributes First, Last, Range,
-or Length, the index number must be omitted for one-dimensional arrays
-and is required for multi-dimensional arrays.
-@end table
-
-@geindex -gnatyb (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyb}
-
-`Blanks not allowed at statement end.'
-
-Trailing blanks are not allowed at the end of statements. The purpose of this
-rule, together with h (no horizontal tabs), is to enforce a canonical format
-for the use of blanks to separate source tokens.
-@end table
-
-@geindex -gnatyB (gcc)
-
-
-@table @asis
-
-@item @code{-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 @code{and then}/@cite{or else} are
-required.
-@end table
-
-@geindex -gnatyc (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyc}
-
-`Check comments, double space.'
-
-Comments must meet the following set of rules:
-
-
-@itemize *
-
-@item 
-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 @code{--} at the start of the comment.
-
-@item 
-Full line comments must have at least two blanks following the
-@code{--} that starts the comment, with the following exceptions.
-
-@item 
-A line consisting only of the @code{--} characters, possibly preceded
-by blanks is permitted.
-
-@item 
-A comment starting with @code{--x} where @code{x} is a special character
-is permitted.
-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 @code{--#} is used). For the purposes of this rule, a
-special character is defined as being in one of the ASCII ranges
-@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 @code{-gnatg} is used).
-
-@item 
-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.
-
-@item 
-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:
-
-@example
----------------------------
--- This is a box comment --
--- with two text lines.  --
----------------------------
-@end example
-@end itemize
-@end table
-
-@geindex -gnatyC (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyC}
-
-`Check comments, single space.'
-
-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)
-
-
-@table @asis
-
-@item @code{-gnatyd}
-
-`Check no DOS line terminators present.'
-
-All lines must be terminated by a single ASCII.LF
-character (in particular the DOS line terminator sequence CR/LF is not
-allowed).
-@end table
-
-@geindex -gnatyD (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyD}
-
-`Check declared identifiers in mixed case.'
-
-Declared identifiers must be in mixed case, as in
-This_Is_An_Identifier. Use -gnatyr in addition to ensure
-that references match declarations.
-@end table
-
-@geindex -gnatye (gcc)
-
-
-@table @asis
-
-@item @code{-gnatye}
-
-`Check end/exit labels.'
-
-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)
-
-
-@table @asis
-
-@item @code{-gnatyf}
-
-`No form feeds or vertical tabs.'
-
-Neither form feeds nor vertical tab characters are permitted
-in the source text.
-@end table
-
-@geindex -gnatyg (gcc)
-
-
-@table @asis
-
-@item @code{-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 @code{-gnatyydISux})
-but additional style switches may be added to this set in the future without
-advance notice.
-@end table
-
-@geindex -gnatyh (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyh}
-
-`No horizontal tabs.'
-
-Horizontal tab characters are not permitted in the source text.
-Together with the b (no blanks at end of line) check, this
-enforces a canonical form for the use of blanks to separate
-source tokens.
-@end table
-
-@geindex -gnatyi (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyi}
-
-`Check if-then layout.'
-
-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)
-
-
-@table @asis
-
-@item @code{-gnatyI}
-
-`check mode IN keywords.'
-
-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)
-
-
-@table @asis
-
-@item @code{-gnatyk}
-
-`Check keyword casing.'
-
-All keywords must be in lower case (with the exception of keywords
-such as @code{digits} used as attribute names to which this check
-does not apply). A single error is reported for each line breaking
-this rule even if multiple casing issues exist on a same line.
-@end table
-
-@geindex -gnatyl (gcc)
-
-
-@table @asis
-
-@item @code{-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 @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
-@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:
-
-@example
-type q is record
-   a : integer;
-   b : integer;
-end record;
-
-type q is
-   record
-      a : integer;
-      b : integer;
-   end record;
-
-type q is
-   record
-      a : integer;
-      b : integer;
-end record;
-@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 @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
-Block : declare
-   A : Integer := 3;
-begin
-   Proc (A, A);
-end Block;
-
-Block :
-   declare
-      A : Integer := 3;
-   begin
-      Proc (A, A);
-   end Block;
-@end example
-
-The same alternative format is allowed for loops. For example, both of
-the following are permitted:
-
-@example
-Clear : while J < 10 loop
-   A (J) := 0;
-end loop Clear;
-
-Clear :
-   while J < 10 loop
-      A (J) := 0;
-   end loop Clear;
-@end example
-@end table
-
-@geindex -gnatyLnnn (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyL}
-
-`Set maximum nesting level.'
-
-The maximum level of nesting of constructs (including subprograms, loops,
-blocks, packages, and conditionals) may not exceed the given value
-`nnn'. A value of zero disconnects this style check.
-@end table
-
-@geindex -gnatym (gcc)
-
-
-@table @asis
-
-@item @code{-gnatym}
-
-`Check maximum line length.'
-
-The length of source lines must not exceed 79 characters, including
-any trailing blanks. The value of 79 allows convenient display on an
-80 character wide device or window, allowing for possible special
-treatment of 80 character lines. Note that this count is of
-characters in the source text. This means that a tab character counts
-as one character in this count and a wide character sequence counts as
-a single character (however many bytes are needed in the encoding).
-@end table
-
-@geindex -gnatyMnnn (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyM}
-
-`Set maximum line length.'
-
-The length of lines must not exceed the
-given value `nnn'. The maximum value that can be specified is 32767.
-If neither style option for setting the line length is used, then the
-default is 255. This also controls the maximum length of lexical elements,
-where the only restriction is that they must fit on a single line.
-@end table
-
-@geindex -gnatyn (gcc)
-
-
-@table @asis
-
-@item @code{-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,
-@code{Integer} and @code{ASCII.NUL}).
-@end table
-
-@geindex -gnatyN (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyN}
-
-`Turn off all style checks.'
-
-All style check options are turned off.
-@end table
-
-@geindex -gnatyo (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyo}
-
-`Check order of subprogram bodies.'
-
-All subprogram bodies in a given scope
-(e.g., a package body) must be in alphabetical order. The ordering
-rule uses normal Ada rules for comparing strings, ignoring casing
-of letters, except that if there is a trailing numeric suffix, then
-the value of this suffix is used in the ordering (e.g., Junk2 comes
-before Junk10).
-@end table
-
-@geindex -gnatyO (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyO}
-
-`Check that overriding subprograms are explicitly marked as such.'
-
-This applies to all subprograms of a derived type that override a primitive
-operation of the type, for both tagged and untagged types. In particular,
-the declaration of a primitive operation of a type extension that overrides
-an inherited operation must carry an overriding indicator. Another case is
-the declaration of a function that overrides a predefined operator (such
-as an equality operator).
-@end table
-
-@geindex -gnatyp (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyp}
-
-`Check pragma casing.'
-
-Pragma 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. An exception is that SPARK_Mode is
-allowed as an alternative for Spark_Mode.
-@end table
-
-@geindex -gnatyr (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyr}
-
-`Check references.'
-
-All identifier references must be cased in the same way as the
-corresponding declaration. No specific casing style is imposed on
-identifiers. The only requirement is for consistency of references
-with declarations.
-@end table
-
-@geindex -gnatys (gcc)
-
-
-@table @asis
-
-@item @code{-gnatys}
-
-`Check separate specs.'
-
-Separate declarations (‘specs’) are required for subprograms (a
-body is not allowed to serve as its own declaration). The only
-exception is that parameterless library level procedures are
-not required to have a separate declaration. This exception covers
-the most frequent form of main program procedures.
-@end table
-
-@geindex -gnatyS (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyS}
-
-`Check no statements after then/else.'
-
-No statements are allowed
-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)
-
-
-@table @asis
-
-@item @code{-gnatyt}
-
-`Check token spacing.'
-
-The following token spacing rules are enforced:
-
-
-@itemize *
-
-@item 
-The keywords @code{abs} and @code{not} must be followed by a space.
-
-@item 
-The token @code{=>} must be surrounded by spaces.
-
-@item 
-The token @code{<>} must be preceded by a space or a left parenthesis.
-
-@item 
-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.
-
-@item 
-Colon-equal (assignment, initialization) must be surrounded by spaces.
-
-@item 
-Comma must be the first non-blank character on the line, or be
-immediately preceded by a non-blank character, and must be followed
-by a space.
-
-@item 
-If the token preceding a left parenthesis ends with a letter or digit, then
-a space must separate the two tokens.
-
-@item 
-If the token following a right parenthesis starts with a letter or digit, then
-a space must separate the two tokens.
-
-@item 
-A right parenthesis must either be the first non-blank character on
-a line, or it must be preceded by a non-blank character.
-
-@item 
-A semicolon must not be preceded by a space, and must not be followed by
-a non-blank character.
-
-@item 
-A unary plus or minus may not be followed by a space.
-
-@item 
-A vertical bar must be surrounded by spaces.
-@end itemize
-
-Exactly one blank (and no other white space) must appear between
-a @code{not} token and a following @code{in} token.
-@end table
-
-@geindex -gnatyu (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyu}
-
-`Check unnecessary blank lines.'
-
-Unnecessary blank lines are not allowed. A blank line is considered
-unnecessary if it appears at the end of the file, or if more than
-one blank line occurs in sequence.
-@end table
-
-@geindex -gnatyx (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyx}
-
-`Check extra parentheses.'
-
-Unnecessary extra level of parentheses (C-style) are not allowed
-around conditions in @code{if} statements, @code{while} statements and
-@code{exit} statements.
-@end table
-
-@geindex -gnatyy (gcc)
-
-
-@table @asis
-
-@item @code{-gnatyy}
-
-`Set all standard style check options.'
-
-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)
-
-
-@table @asis
-
-@item @code{-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 the @code{L} parameter without any integer value after that, because any
-digit following `-' 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 `-'.
-@end table
-
-@geindex -gnaty+ (gcc)
-
-
-@table @asis
-
-@item @code{-gnaty+}
-
-`Enable style check options.'
-
-This causes any subsequent options in the string to enable the corresponding
-style check option. That is, it cancels the effect of a previous -,
-if any.
-@end table
-
-@c end of switch description (leave this comment to ease automatic parsing for
-
-@c GNAT Studio)
-
-In the above rules, appearing in column one is always permitted, that is,
-counts as meeting either a requirement for a required preceding space,
-or as meeting a requirement for no preceding space.
-
-Appearing at the end of a line is also always permitted, that is, counts
-as meeting either a requirement for a following space, or as meeting
-a requirement for no following space.
-
-If any of these style rules is violated, a message is generated giving
-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 @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 @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.
-
-@node Run-Time Checks,Using gcc for Syntax Checking,Style Checking,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id19}@anchor{f5}@anchor{gnat_ugn/building_executable_programs_with_gnat run-time-checks}@anchor{ea}
-@subsection Run-Time Checks
-
-
-@geindex Division by zero
-
-@geindex Access before elaboration
-
-@geindex Checks
-@geindex division by zero
-
-@geindex Checks
-@geindex access before elaboration
-
-@geindex Checks
-@geindex stack overflow checking
-
-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 @code{gcc}
-switches refine this default behavior.
-
-@geindex -gnatp (gcc)
-
-
-@table @asis
-
-@item @code{-gnatp}
-
-@geindex Suppressing checks
-
-@geindex Checks
-@geindex suppressing
-
-This switch causes the unit to be compiled
-as though @code{pragma Suppress (All_checks)}
-had been present in the source. Validity checks are also eliminated (in
-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.
-
-Note that when checks are suppressed, the compiler is allowed, but not
-required, to omit the checking code. If the run-time cost of the
-checking code is zero or near-zero, the compiler will generate it even
-if checks are suppressed. In particular, if the compiler can prove
-that a certain check will necessarily fail, it will generate code to
-do an unconditional ‘raise’, even if checks are suppressed. The
-compiler warns in this case. Another case in which checks may not be
-eliminated is when they are embedded in certain run-time routines such
-as math library routines.
-
-Of course, run-time checks are omitted whenever the compiler can prove
-that they will not fail, whether or not checks are suppressed.
-
-Note that if you suppress a check that would have failed, program
-execution is erroneous, which means the behavior is totally
-unpredictable. The program might crash, or print wrong answers, or
-do anything else. It might even do exactly what you wanted it to do
-(and then it might start failing mysteriously next week or next
-year). The compiler will generate code based on the assumption that
-the condition being checked is true, which can result in erroneous
-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 @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 @code{Unsuppress} either as a configuration pragma or as
-a local pragma to make sure that a specified check is performed
-even if @code{gnatp} is specified.
-
-The @code{-gnatp} switch has no effect if a subsequent
-@code{-gnat-p} switch appears.
-@end table
-
-@geindex -gnat-p (gcc)
-
-@geindex Suppressing checks
-
-@geindex Checks
-@geindex suppressing
-
-@geindex Suppress
-
-
-@table @asis
-
-@item @code{-gnat-p}
-
-This switch cancels the effect of a previous @code{gnatp} switch.
-@end table
-
-@geindex -gnato?? (gcc)
-
-@geindex Overflow checks
-
-@geindex Overflow mode
-
-@geindex Check
-@geindex overflow
-
-
-@table @asis
-
-@item @code{-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
-the ‘Overflow Check Handling in GNAT’ appendix in this
-User’s Guide.
-
-Overflow checks are always enabled by this switch. The argument
-controls the mode, using the codes
-
-
-@table @asis
-
-@item `1 = STRICT'
-
-In STRICT mode, intermediate operations are always done using the
-base type, and overflow checking ensures that the result is within
-the base type range.
-
-@item `2 = MINIMIZED'
-
-In MINIMIZED mode, overflows in intermediate operations are avoided
-where possible by using a larger integer type for the computation
-(typically @code{Long_Long_Integer}). Overflow checking ensures that
-the result fits in this larger integer type.
-
-@item `3 = ELIMINATED'
-
-In ELIMINATED mode, overflows in intermediate operations are avoided
-by using multi-precision arithmetic. In this case, overflow checking
-has no effect on intermediate operations (since overflow is impossible).
-@end table
-
-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
-postcondition expressions).
-
-If one digit is present, the corresponding mode is applicable to both
-expressions within and outside assertion expressions.
-
-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 @code{-gnato} in previous versions of GNAT.
-
-@geindex Machine_Overflows
-
-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 @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).
-
-The reason that we distinguish overflow checking from other kinds of
-range constraint checking is that a failure of an overflow check, unlike
-for example the failure of a range check, can result in an incorrect
-value, but cannot cause random memory destruction (like an out of range
-subscript), or a wild jump (from an out of range case value). Overflow
-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 @code{-gnato11} (equivalent to @code{-gnato1}),
-so overflow checking is performed in STRICT mode by default.
-@end table
-
-@geindex -gnatE (gcc)
-
-@geindex Elaboration checks
-
-@geindex Check
-@geindex elaboration
-
-
-@table @asis
-
-@item @code{-gnatE}
-
-Enables dynamic checks for access-before-elaboration
-on subprogram calls and generic instantiations.
-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{c7,,Compiling with gcc}.
-@end table
-
-@geindex -fstack-check (gcc)
-
-@geindex Stack Overflow Checking
-
-@geindex Checks
-@geindex stack overflow checking
-
-
-@table @asis
-
-@item @code{-fstack-check}
-
-Activates stack overflow checking. For full details of the effect and use of
-this switch see @ref{e5,,Stack Overflow Checking}.
-@end table
-
-@geindex Unsuppress
-
-The setting of these switches only controls the default setting of the
-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{f6}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-syntax-checking}@anchor{f7}
-@subsection Using @code{gcc} for Syntax Checking
-
-
-@geindex -gnats (gcc)
-
-
-@table @asis
-
-@item @code{-gnats}
-
-The @code{s} stands for ‘syntax’.
-
-Run GNAT in syntax checking only mode. For
-example, the command
-
-@example
-$ gcc -c -gnats x.adb
-@end example
-
-compiles file @code{x.adb} in syntax-check-only mode. You can check a
-series of files in a single command
-, and can use wildcards to specify such a group of files.
-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 @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,
-the output is a warning:
-
-@example
-$ gcc -c -gnats -x ada toto.txt
-toto.txt:1:01: warning: empty file, contains no compilation units
-$
-@end example
-
-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 @code{X}
-`with's a unit @code{Y}, compiling unit @code{X} in syntax
-check only mode does not access the source file containing unit
-@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 @code{gnatchop} utility
-(@ref{1d,,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{f8}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-semantic-checking}@anchor{f9}
-@subsection Using @code{gcc} for Semantic Checking
-
-
-@geindex -gnatc (gcc)
-
-
-@table @asis
-
-@item @code{-gnatc}
-
-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
-(no object file is generated).
-
-Because dependent files must be accessed, you must follow the GNAT
-semantic restrictions on file structuring to operate in this mode:
-
-
-@itemize *
-
-@item 
-The needed source files must be accessible
-(see @ref{73,,Search Paths and the Run-Time Library (RTL)}).
-
-@item 
-Each file must contain only one compilation unit.
-
-@item 
-The file name and unit name must match (@ref{3b,,File Naming Rules}).
-@end itemize
-
-The output consists of error messages as appropriate. No object file is
-generated. An @code{ALI} file is generated for use in the context of
-cross-reference tools, but this file is marked as not being suitable
-for binding (since no object file is generated).
-The checking corresponds exactly to the notion of
-legality in the Ada Reference Manual.
-
-Any unit can be compiled in semantics-checking-only mode, including
-units that would not normally be compiled (subunits,
-and specifications where a separate body is present).
-@end table
-
-@node Compiling Different Versions of Ada,Character Set Control,Using gcc for Semantic Checking,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-different-versions-of-ada}@anchor{6}@anchor{gnat_ugn/building_executable_programs_with_gnat id22}@anchor{fa}
-@subsection Compiling Different Versions of Ada
-
-
-The switches described in this section allow you to explicitly specify
-the version of the Ada language that your programs are written in.
-The default mode is Ada 2012,
-but you can also specify Ada 95, Ada 2005 mode, or
-indicate Ada 83 compatibility mode.
-
-@geindex Compatibility with Ada 83
-
-@geindex -gnat83 (gcc)
-
-@geindex ACVC
-@geindex Ada 83 tests
-
-@geindex Ada 83 mode
-
-
-@table @asis
-
-@item @code{-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
-@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
-found in earlier ACVC tests (and that have been removed from the ACATS suite
-for Ada 95), might not compile correctly.
-Nevertheless, this switch may be useful in some circumstances, for example
-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 @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
-@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 `Compatibility and Porting Guide' chapter in the
-@cite{GNAT Reference Manual}.
-@end table
-
-@geindex -gnat95 (gcc)
-
-@geindex Ada 95 mode
-
-
-@table @asis
-
-@item @code{-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 @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
-@code{-gnat83}, @code{-gnat05/2005}, or @code{-gnat12/2012}
-switch earlier in the command line.
-@end table
-
-@geindex -gnat05 (gcc)
-
-@geindex -gnat2005 (gcc)
-
-@geindex Ada 2005 mode
-
-
-@table @asis
-
-@item @code{-gnat05} or @code{-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
-@code{-gnat83} and @code{-gnat95} switches for further
-information).
-@end table
-
-@geindex -gnat12 (gcc)
-
-@geindex -gnat2012 (gcc)
-
-@geindex Ada 2012 mode
-
-
-@table @asis
-
-@item @code{-gnat12} or @code{-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
-@code{-gnat83}, @code{-gnat95}, and @code{-gnat05/2005} switches
-for further information).
-@end table
-
-@geindex -gnat2022 (gcc)
-
-@geindex Ada 2022 mode
-
-
-@table @asis
-
-@item @code{-gnat2022} (Ada 2022 mode)
-
-This switch directs the compiler to implement the Ada 2022 version of the
-language.
-@end table
-
-@geindex -gnatX0 (gcc)
-
-@geindex Ada language extensions
-
-@geindex GNAT extensions
-
-
-@table @asis
-
-@item @code{-gnatX0} (Enable GNAT Extensions)
-
-This switch directs the compiler to implement the latest version of the
-language (currently Ada 2022) and also to enable certain GNAT implementation
-extensions that are not part of any Ada standard. For a full list of these
-extensions, see the GNAT reference manual, @code{Pragma Extensions_Allowed}.
-@end table
-
-@geindex -gnatX (gcc)
-
-@geindex Ada language extensions
-
-@geindex GNAT extensions
-
-
-@table @asis
-
-@item @code{-gnatX} (Enable core GNAT Extensions)
-
-This switch is similar to -gnatX0 except that only some, not all, of the
-GNAT-defined language extensions are enabled. For a list of the
-extensions enabled by this switch, see the GNAT reference manual
-@code{Pragma Extensions_Allowed} and the description of that pragma’s
-“On” (as opposed to “All”) argument.
-@end table
-
-@node Character Set Control,File Naming Control,Compiling Different Versions of Ada,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat character-set-control}@anchor{31}@anchor{gnat_ugn/building_executable_programs_with_gnat id23}@anchor{fb}
-@subsection Character Set Control
-
-
-@geindex -gnati (gcc)
-
-
-@table @asis
-
-@item @code{-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. @code{c} is a
-single character  indicating the character set, as follows:
-
-
-@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@item
-
-`1'
-
-@tab
-
-ISO 8859-1 (Latin-1) identifiers
-
-@item
-
-`2'
-
-@tab
-
-ISO 8859-2 (Latin-2) letters allowed in identifiers
-
-@item
-
-`3'
-
-@tab
-
-ISO 8859-3 (Latin-3) letters allowed in identifiers
-
-@item
-
-`4'
-
-@tab
-
-ISO 8859-4 (Latin-4) letters allowed in identifiers
-
-@item
-
-`5'
-
-@tab
-
-ISO 8859-5 (Cyrillic) letters allowed in identifiers
-
-@item
-
-`9'
-
-@tab
-
-ISO 8859-15 (Latin-9) letters allowed in identifiers
-
-@item
-
-`p'
-
-@tab
-
-IBM PC letters (code page 437) allowed in identifiers
-
-@item
-
-`8'
-
-@tab
-
-IBM PC letters (code page 850) allowed in identifiers
-
-@item
-
-`f'
-
-@tab
-
-Full upper-half codes allowed in identifiers
-
-@item
-
-`n'
-
-@tab
-
-No upper-half codes allowed in identifiers
-
-@item
-
-`w'
-
-@tab
-
-Wide-character codes (that is, codes greater than 255)
-allowed in identifiers
-
-@end multitable
-
-
-See @ref{23,,Foreign Language Representation} for full details on the
-implementation of these character sets.
-@end table
-
-@geindex -gnatW (gcc)
-
-
-@table @asis
-
-@item @code{-gnatW`e'}
-
-Specify the method of encoding for wide characters.
-@code{e} is one of the following:
-
-
-@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@item
-
-`h'
-
-@tab
-
-Hex encoding (brackets coding also recognized)
-
-@item
-
-`u'
-
-@tab
-
-Upper half encoding (brackets encoding also recognized)
-
-@item
-
-`s'
-
-@tab
-
-Shift/JIS encoding (brackets encoding also recognized)
-
-@item
-
-`e'
-
-@tab
-
-EUC encoding (brackets encoding also recognized)
-
-@item
-
-`8'
-
-@tab
-
-UTF-8 encoding (brackets encoding also recognized)
-
-@item
-
-`b'
-
-@tab
-
-Brackets encoding only (default value)
-
-@end multitable
-
-
-For full details on these encoding
-methods see @ref{37,,Wide_Character Encodings}.
-Note that brackets coding is always accepted, even if one of the other
-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
-used, it must be used consistently throughout the program. However,
-since brackets encoding is always recognized, it may be conveniently
-used in standard libraries, allowing these libraries to be used with
-any of the available coding schemes.
-
-Note that brackets encoding only applies to program text. Within comments,
-brackets are considered to be normal graphic characters, and bracket sequences
-are never recognized as wide characters.
-
-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
-skipped and the default representation for the file is set to UTF-8.
-
-Note that the wide character representation that is specified (explicitly
-or by default) for the main program also acts as the default encoding used
-for Wide_Text_IO files if not specifically overridden by a WCEM form
-parameter.
-@end table
-
-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
-characters in the range 16#00#..16#1F# are not accepted in program text
-or in comments. Upper half control characters (16#80#..16#9F#) are rejected
-in program text, but allowed and ignored in comments. Note in particular
-that the Next Line (NEL) character whose encoding is 16#85# is not recognized
-as an end of line in this default mode. If your source program contains
-instances of the NEL character used as a line terminator,
-you must use UTF-8 encoding for the whole
-source program. In default mode, all lines must be ended by a standard
-end of line sequence (CR, CR/LF, or LF).
-
-Note that the convention of simply accepting all upper half characters in
-comments means that programs that use standard ASCII for program text, but
-UTF-8 encoding for comments are accepted in default mode, providing that the
-comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator.
-This is a common mode for many programs with foreign language comments.
-
-@node File Naming Control,Subprogram Inlining Control,Character Set Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat file-naming-control}@anchor{fc}@anchor{gnat_ugn/building_executable_programs_with_gnat id24}@anchor{fd}
-@subsection File Naming Control
-
-
-@geindex -gnatk (gcc)
-
-
-@table @asis
-
-@item @code{-gnatk`n'}
-
-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.
-
-For the source file naming rules, @ref{3b,,File Naming Rules}.
-@end table
-
-@node Subprogram Inlining Control,Auxiliary Output Control,File Naming Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id25}@anchor{fe}@anchor{gnat_ugn/building_executable_programs_with_gnat subprogram-inlining-control}@anchor{ff}
-@subsection Subprogram Inlining Control
-
-
-@geindex -gnatn (gcc)
-
-
-@table @asis
-
-@item @code{-gnatn[12]}
-
-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 units is not performed. If you want to additionally
-enable inlining of subprograms specified by pragma @code{Inline} across units,
-you must also specify this switch.
-
-In the absence of this switch, GNAT does not attempt inlining across units
-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
-units, which is a good compromise between compilation times and performances
-at run time, or 2 for full inlining across units, 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 @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
-where possible, the call will be inlined.
-For further details on when inlining is possible
-see @ref{100,,Inlining of Subprograms}.
-@end table
-
-@geindex -gnatN (gcc)
-
-
-@table @asis
-
-@item @code{-gnatN}
-
-This switch activates front-end inlining which also
-generates additional dependencies.
-
-When using a gcc-based back end, then the use of
-@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
-
-@node Auxiliary Output Control,Debugging Control,Subprogram Inlining Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat auxiliary-output-control}@anchor{101}@anchor{gnat_ugn/building_executable_programs_with_gnat id26}@anchor{102}
-@subsection Auxiliary Output Control
-
-
-@geindex -gnatu (gcc)
-
-
-@table @asis
-
-@item @code{-gnatu}
-
-Print a list of units required by this compilation on @code{stdout}.
-The listing includes all units on which the unit being compiled depends
-either directly or indirectly.
-@end table
-
-@geindex -pass-exit-codes (gcc)
-
-
-@table @asis
-
-@item @code{-pass-exit-codes}
-
-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 @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:
-
-
-@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@item
-
-`5'
-
-@tab
-
-There was an error in at least one source file.
-
-@item
-
-`3'
-
-@tab
-
-At least one source file did not generate an object file.
-
-@item
-
-`2'
-
-@tab
-
-The compiler died unexpectedly (internal error for example).
-
-@item
-
-`0'
-
-@tab
-
-An object file has been generated for every source file.
-
-@end multitable
-
-@end table
-
-@node Debugging Control,Exception Handling Control,Auxiliary Output Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-control}@anchor{103}@anchor{gnat_ugn/building_executable_programs_with_gnat id27}@anchor{104}
-@subsection Debugging Control
-
-
-@quotation
-
-@geindex Debugging options
-@end quotation
-
-@geindex -gnatd (gcc)
-
-
-@table @asis
-
-@item @code{-gnatd`x'}
-
-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 @code{Debug} unit in the compiler source
-file @code{debug.adb}.
-@end table
-
-@geindex -gnatG (gcc)
-
-
-@table @asis
-
-@item @code{-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
-lower level constructs. For example, tasking operations are transformed
-into calls to the tasking run-time routines. A unique capability of GNAT
-is to list this expanded code in a form very close to normal Ada source.
-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 @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 @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.
-
-The format of the output is very similar to standard Ada source, and is
-easily understood by an Ada programmer. The following special syntactic
-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 @code{Sprint} in file @code{sprint.ads} for a full list.
-
-@geindex -gnatL (gcc)
-
-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).
-
-
-@table @asis
-
-@item @code{new @var{xxx} [storage_pool = @var{yyy}]}
-
-Shows the storage pool being used for an allocator.
-
-@item @code{at end @var{procedure-name};}
-
-Shows the finalization (cleanup) procedure for a scope.
-
-@item @code{(if @var{expr} then @var{expr} else @var{expr})}
-
-Conditional expression equivalent to the @code{x?y:z} construction in C.
-
-@item @code{@var{target}^(@var{source})}
-
-A conversion with floating-point truncation instead of rounding.
-
-@item @code{@var{target}?(@var{source})}
-
-A conversion that bypasses normal Ada semantic checking. In particular
-enumeration types and fixed-point types are treated simply as integers.
-
-@item @code{@var{target}?^(@var{source})}
-
-Combines the above two cases.
-@end table
-
-@code{@var{x} #/ @var{y}}
-
-@code{@var{x} #mod @var{y}}
-
-@code{@var{x} # @var{y}}
-
-
-@table @asis
-
-@item @code{@var{x} #rem @var{y}}
-
-A division or multiplication of fixed-point values which are treated as
-integers without any kind of scaling.
-
-@item @code{free @var{expr} [storage_pool = @var{xxx}]}
-
-Shows the storage pool associated with a @code{free} statement.
-
-@item @code{[subtype or type declaration]}
-
-Used to list an equivalent declaration for an internally generated
-type that is referenced elsewhere in the listing.
-
-@item @code{freeze @var{type-name} [@var{actions}]}
-
-Shows the point at which @code{type-name} is frozen, with possible
-associated actions to be performed at the freeze point.
-
-@item @code{reference @var{itype}}
-
-Reference (and hence definition) to internal type @code{itype}.
-
-@item @code{@var{function-name}! (@var{arg}, @var{arg}, @var{arg})}
-
-Intrinsic function call.
-
-@item @code{@var{label-name} : label}
-
-Declaration of label @code{labelname}.
-
-@item @code{#$ @var{subprogram-name}}
-
-An implicit call to a run-time support routine
-(to meet the requirement of H.3.1(9) in a
-convenient manner).
-
-@item @code{@var{expr} && @var{expr} && @var{expr} ... && @var{expr}}
-
-A multiple concatenation (same effect as @code{expr} & @code{expr} &
-@code{expr}, but handled more efficiently).
-
-@item @code{[constraint_error]}
-
-Raise the @code{Constraint_Error} exception.
-
-@item @code{@var{expression}'reference}
-
-A pointer to the result of evaluating @{expression@}.
-
-@item @code{@var{target-type}!(@var{source-expression})}
-
-An unchecked conversion of @code{source-expression} to @code{target-type}.
-
-@item @code{[@var{numerator}/@var{denominator}]}
-
-Used to represent internal real literals (that) have no exact
-representation in base 2-16 (for example, the result of compile time
-evaluation of the expression 1.0/27.0).
-@end table
-@end table
-
-@geindex -gnatD (gcc)
-
-
-@table @asis
-
-@item @code{-gnatD[=nn]}
-
-When used in conjunction with @code{-gnatG}, this switch causes
-the expanded source, as described above for
-@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 @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
-@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 @code{-gnatD} actually implies @code{-gnatG}
-automatically, so it is not necessary to give both options.
-In other words @code{-gnatD} is equivalent to @code{-gnatDG}).
-
-@geindex -gnatL (gcc)
-
-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 @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.
-@end table
-
-@geindex -gnatr (gcc)
-
-@geindex pragma Restrictions
-
-
-@table @asis
-
-@item @code{-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
-or investigated. The switch also causes pragma Profile to be treated as
-Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
-restriction warnings rather than restrictions.
-@end table
-
-@geindex -gnatR (gcc)
-
-
-@table @asis
-
-@item @code{-gnatR[0|1|2|3|4][e][j][m][s]}
-
-This switch controls output from the compiler of a listing showing
-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).
-
-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.
-
-For @code{-gnatR4}, information for relevant compiler-generated types
-is also listed, i.e. when they are structurally part of other declared
-types and objects.
-
-If the switch is followed by an @code{e} (e.g. @code{-gnatR2e}), then
-extended representation information for record sub-components of records
-is included.
-
-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 a @code{j} (e.g., @code{-gnatRj}), then
-the output is in the JSON data interchange format specified by the
-ECMA-404 standard. The semantic description of this JSON output is
-available in the specification of the Repinfo unit present in the
-compiler sources.
-
-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 @code{file} is
-the name of the corresponding source file, except if @code{j} is also
-specified, in which case the file name is @code{file.json}.
-
-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 @code{at 0 range 0 .. -1}.
-@end table
-
-@geindex -gnatS (gcc)
-
-
-@table @asis
-
-@item @code{-gnatS}
-
-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
-do this entirely in standard Ada (since new
-numeric base types cannot be created in standard
-Ada), but the output is easily
-readable to any Ada programmer, and is useful to
-determine the characteristics of target dependent
-types in package Standard.
-@end table
-
-@geindex -gnatx (gcc)
-
-
-@table @asis
-
-@item @code{-gnatx}
-
-Normally the compiler generates full cross-referencing information in
-the @code{ALI} file. This information is used by a number of tools.
-The @code{-gnatx} switch suppresses this information. This saves some space
-and may slightly speed up compilation, but means that tools depending
-on this information cannot be used.
-@end table
-
-@geindex -fgnat-encodings (gcc)
-
-
-@table @asis
-
-@item @code{-fgnat-encodings=[all|gdb|minimal]}
-
-This switch controls the balance between GNAT encodings and standard DWARF
-emitted in the debug information.
-
-Historically, old debug formats like stabs were not powerful enough to
-express some Ada types (for instance, variant records or fixed-point types).
-To work around this, GNAT introduced proprietary encodings that embed the
-missing information (“GNAT encodings”).
-
-Recent versions of the DWARF debug information format are now able to
-correctly describe most of these Ada constructs (“standard DWARF”). As
-third-party tools started to use this format, GNAT has been enhanced to
-generate it. However, most tools (including GDB) are still relying on GNAT
-encodings.
-
-To support all tools, GNAT needs to be versatile about the balance between
-generation of GNAT encodings and standard DWARF. This is what
-@code{-fgnat-encodings} is about.
-
-
-@itemize *
-
-@item 
-@code{=all}: Emit all GNAT encodings, and then emit as much standard DWARF as
-possible so it does not conflict with GNAT encodings.
-
-@item 
-@code{=gdb}: Emit as much standard DWARF as possible as long as the current
-GDB handles it. Emit GNAT encodings for the rest.
-
-@item 
-@code{=minimal}: Emit as much standard DWARF as possible and emit GNAT
-encodings for the rest.
-@end itemize
-@end table
-
-@node Exception Handling Control,Units to Sources Mapping Files,Debugging Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat exception-handling-control}@anchor{105}@anchor{gnat_ugn/building_executable_programs_with_gnat id28}@anchor{106}
-@subsection Exception Handling Control
-
-
-GNAT uses two methods for handling exceptions at run time. The
-@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 propagation, but introduces significant overhead for
-the use of exception handlers, even if no exception is raised.
-
-The other approach is called ‘zero cost’ exception handling.
-With this method, the compiler builds static tables to describe
-the exception ranges. No dynamic code is required when entering
-a frame containing an exception handler. When an exception is
-raised, the tables are used to control a back trace of the
-subprogram invocation stack to locate the required exception
-handler. This method has considerably poorer performance for
-the propagation of exceptions, but there is no overhead for
-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 @code{-funwind-tables} GCC’s
-option.
-
-The following switches may be used to control which of the
-two exception handling methods is used.
-
-@geindex --RTS=sjlj (gnatmake)
-
-
-@table @asis
-
-@item @code{--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
-this switch can be used to modify this default, and must be
-used for all units in the partition.
-This option is rarely used. One case in which it may be
-advantageous is if you have an application where exception
-raising is common and the overall performance of the
-application is improved by favoring exception propagation.
-@end table
-
-@geindex --RTS=zcx (gnatmake)
-
-@geindex Zero Cost Exceptions
-
-
-@table @asis
-
-@item @code{--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
-mechanism for the target is setjmp/longjmp exceptions, then
-this switch can be used to modify this default, and must be
-used for all units in the partition.
-This option can only be used if the zero cost approach
-is available for the target in use, otherwise it will generate an error.
-@end table
-
-The same option @code{--RTS} must be used both for @code{gcc}
-and @code{gnatbind}. Passing this option to @code{gnatmake}
-(@ref{ce,,Switches for gnatmake}) will ensure the required consistency
-through the compilation and binding steps.
-
-@node Units to Sources Mapping Files,Code Generation Control,Exception Handling Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id29}@anchor{107}@anchor{gnat_ugn/building_executable_programs_with_gnat units-to-sources-mapping-files}@anchor{e8}
-@subsection Units to Sources Mapping Files
-
-
-@geindex -gnatem (gcc)
-
-
-@table @asis
-
-@item @code{-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
-are used by the compiler to short-circuit the path search.
-
-The use of mapping files is not required for correct operation of the
-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 @code{-gnatem} switch is not a switch that you would use
-explicitly. It is intended primarily for use by automatic tools such as
-@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 @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:
-
-@example
-main%b
-main.2.ada
-/gnat/project1/sources/main.2.ada
-@end example
-
-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 @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, @code{gnatmake} creates a temporary
-mapping file and communicates it to the compiler using this switch.
-@end table
-
-@node Code Generation Control,,Units to Sources Mapping Files,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat code-generation-control}@anchor{108}@anchor{gnat_ugn/building_executable_programs_with_gnat id30}@anchor{109}
-@subsection Code Generation Control
-
-
-The GCC technology provides a wide range of target dependent
-@code{-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 @code{-m} switches may be
-found in the GCC documentation.
-
-Use of these @code{-m} switches may in some cases result in improved
-code performance.
-
-The GNAT technology is tested and qualified without any
-@code{-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 @code{-m} switches unless
-special needs lead to requirements in this area. In particular,
-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
-@anchor{gnat_ugn/building_executable_programs_with_gnat id31}@anchor{10a}@anchor{gnat_ugn/building_executable_programs_with_gnat linker-switches}@anchor{10b}
-@section Linker Switches
-
-
-Linker switches can be specified after @code{-largs} builder switch.
-
-@geindex -fuse-ld=name
-
-
-@table @asis
-
-@item @code{-fuse-ld=`name'}
-
-Linker to be used. The default is @code{bfd} for @code{ld.bfd}; @code{gold}
-(for @code{ld.gold}) and @code{mold} (for @code{ld.mold}) are more
-recent and faster alternatives, but only available on GNU/Linux
-platforms.
-
-@end table
-
-@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{c8}@anchor{gnat_ugn/building_executable_programs_with_gnat id32}@anchor{10c}
-@section Binding with @code{gnatbind}
-
-
-@geindex gnatbind
-
-This chapter describes the GNAT binder, @code{gnatbind}, which is used
-to bind compiled GNAT objects.
-
-The @code{gnatbind} program performs four separate functions:
-
-
-@itemize *
-
-@item 
-Checks that a program is consistent, in accordance with the rules in
-Chapter 10 of the Ada Reference Manual. In particular, error
-messages are generated if a program uses inconsistent versions of a
-given unit.
-
-@item 
-Checks that an acceptable order of elaboration exists for the program
-and issues an error message if it cannot find an order of elaboration
-that satisfies the rules in Chapter 10 of the Ada Language Manual.
-
-@item 
-Generates a main program incorporating the given elaboration order.
-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 @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 @code{gnatlink} utility used to link the Ada application.
-@end itemize
-
-@menu
-* Running gnatbind:: 
-* Switches for gnatbind:: 
-* Command-Line Access:: 
-* Search Paths for gnatbind:: 
-* Examples of gnatbind Usage:: 
-
-@end menu
-
-@node Running gnatbind,Switches for gnatbind,,Binding with gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat id33}@anchor{10d}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatbind}@anchor{10e}
-@subsection Running @code{gnatbind}
-
-
-The form of the @code{gnatbind} command is
-
-@example
-$ gnatbind [ switches ] mainprog[.ali] [ switches ]
-@end example
-
-where @code{mainprog.adb} is the Ada file containing the main program
-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
-parameter @code{hello.ali}, for a main program contained in file
-@code{hello.adb}, the binder output files would be @code{b~hello.ads}
-and @code{b~hello.adb}.
-
-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 @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
-@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
-resulted from compiling this version of the source file (or in the case
-where the source checksums match, a version close enough that the
-difference does not matter).
-
-@geindex Source files
-@geindex use by binder
-
-The effect of this consistency checking, which includes source files, is
-that the binder ensures that the program is consistent with the latest
-version of the source files that can be located at bind time. Editing a
-source file without compiling files that depend on the source file cause
-error messages to be generated by the binder.
-
-For example, suppose you have a main program @code{hello.adb} and a
-package @code{P}, from file @code{p.ads} and you perform the following
-steps:
-
-
-@itemize *
-
-@item 
-Enter @code{gcc -c hello.adb} to compile the main program.
-
-@item 
-Enter @code{gcc -c p.ads} to compile package @code{P}.
-
-@item 
-Edit file @code{p.ads}.
-
-@item 
-Enter @code{gnatbind hello}.
-@end itemize
-
-At this point, the file @code{p.ali} contains an out-of-date time stamp
-because the file @code{p.ads} has been edited. The attempt at binding
-fails, and the binder generates the following error messages:
-
-@example
-error: "hello.adb" must be recompiled ("p.ads" has been modified)
-error: "p.ads" has been modified and must be recompiled
-@end example
-
-Now both files must be recompiled as indicated, and then the bind can
-succeed, generating a main program. You need not normally be concerned
-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 @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 @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{10f}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatbind}@anchor{110}
-@subsection Switches for @code{gnatbind}
-
-
-The following switches are available with @code{gnatbind}; details will
-be presented in subsequent sections.
-
-@geindex --version (gnatbind)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display Copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatbind)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
-
-@geindex -a (gnatbind)
-
-
-@table @asis
-
-@item @code{-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
-shared Stand-Alone Libraries.
-@end table
-
-@geindex -aO (gnatbind)
-
-
-@table @asis
-
-@item @code{-aO}
-
-Specify directory to be searched for ALI files.
-@end table
-
-@geindex -aI (gnatbind)
-
-
-@table @asis
-
-@item @code{-aI}
-
-Specify directory to be searched for source file.
-@end table
-
-@geindex -A (gnatbind)
-
-
-@table @asis
-
-@item @code{-A[=`filename']}
-
-Output ALI list (to standard output or to the named file).
-@end table
-
-@geindex -b (gnatbind)
-
-
-@table @asis
-
-@item @code{-b}
-
-Generate brief messages to @code{stderr} even if verbose mode set.
-@end table
-
-@geindex -c (gnatbind)
-
-
-@table @asis
-
-@item @code{-c}
-
-Check only, no generation of binder output file.
-@end table
-
-@geindex -dnn[k|m] (gnatbind)
-
-
-@table @asis
-
-@item @code{-d`nn'[k|m]}
-
-This switch can be used to change the default task stack size value
-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
-
-@example
-pragma Storage_Size (nn);
-@end example
-
-When they do not already have such a pragma.
-@end table
-
-@geindex -D (gnatbind)
-
-
-@table @asis
-
-@item @code{-D`nn'[k|m]}
-
-Set the default secondary stack size to @code{nn}. The suffix indicates whether
-the size is in bytes (no suffix), kilobytes (@code{k} suffix) or megabytes
-(@code{m} suffix).
-
-The secondary stack holds objects of unconstrained types that are returned by
-functions, for example unconstrained Strings. The size of the secondary stack
-can be dynamic or fixed depending on the target.
-
-For most targets, the secondary stack grows on demand and is implemented as
-a chain of blocks in the heap. In this case, the default secondary stack size
-determines the initial size of the secondary stack for each task and the
-smallest amount the secondary stack can grow by.
-
-For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is
-fixed. This switch can be used to change the default size of these stacks.
-The default secondary stack size can be overridden on a per-task basis if
-individual tasks have different secondary stack requirements. This is
-achieved through the Secondary_Stack_Size aspect that takes the size of the
-secondary stack in bytes.
-@end table
-
-@geindex -e (gnatbind)
-
-
-@table @asis
-
-@item @code{-e}
-
-Output complete list of elaboration-order dependencies.
-@end table
-
-@geindex -Ea (gnatbind)
-
-
-@table @asis
-
-@item @code{-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 @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)
-
-
-@table @asis
-
-@item @code{-Es}
-
-Store tracebacks in exception occurrences when the target supports it.
-The “s” is for “symbolic”; symbolic tracebacks are enabled.
-@end table
-
-@geindex -E (gnatbind)
-
-
-@table @asis
-
-@item @code{-E}
-
-Currently the same as @code{-Ea}.
-@end table
-
-@geindex -f (gnatbind)
-
-
-@table @asis
-
-@item @code{-f`elab-order'}
-
-Force elaboration order. For further details see @ref{111,,Elaboration Control}
-and @ref{f,,Elaboration Order Handling in GNAT}.
-@end table
-
-@geindex -F (gnatbind)
-
-
-@table @asis
-
-@item @code{-F}
-
-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
-Library through a pragma Import and only specifying through a linker switch
-this Stand-Alone Library. This switch is used to guarantee that elaboration
-flag checks are generated.
-@end table
-
-@geindex -h (gnatbind)
-
-
-@table @asis
-
-@item @code{-h}
-
-Output usage (help) information.
-@end table
-
-@geindex -H (gnatbind)
-
-
-@table @asis
-
-@item @code{-H}
-
-Legacy elaboration order model enabled. For further details see
-@ref{f,,Elaboration Order Handling in GNAT}.
-@end table
-
-@geindex -H32 (gnatbind)
-
-
-@table @asis
-
-@item @code{-H32}
-
-Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types).
-For further details see @ref{112,,Dynamic Allocation Control}.
-@end table
-
-@geindex -H64 (gnatbind)
-
-@geindex __gnat_malloc
-
-
-@table @asis
-
-@item @code{-H64}
-
-Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types).
-For further details see @ref{112,,Dynamic Allocation Control}.
-
-@geindex -I (gnatbind)
-
-@item @code{-I}
-
-Specify directory to be searched for source and ALI files.
-
-@geindex -I- (gnatbind)
-
-@item @code{-I-}
-
-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 @code{gnatbind} command line.
-
-@geindex -k (gnatbind)
-
-@item @code{-k}
-
-Disable checking of elaboration flags. When using @code{-n}
-either explicitly or implicitly, @code{-F} is also implied,
-unless @code{-k} is used. This switch should be used with care
-and you should ensure manually that elaboration routines are not called
-twice unintentionally.
-
-@geindex -K (gnatbind)
-
-@item @code{-K}
-
-Give list of linker options specified for link.
-
-@geindex -l (gnatbind)
-
-@item @code{-l}
-
-Output chosen elaboration order.
-
-@geindex -L (gnatbind)
-
-@item @code{-L`xxx'}
-
-Bind the units for library building. In this case the @code{adainit} and
-@code{adafinal} procedures (@ref{a0,,Binding with Non-Ada Main Programs})
-are renamed to @code{@var{xxx}init} and
-@code{@var{xxx}final}.
-Implies -n.
-(@ref{2a,,GNAT and Libraries}, for more details.)
-
-@geindex -M (gnatbind)
-
-@item @code{-M`xyz'}
-
-Rename generated main program from main to xyz. This option is
-supported on cross environments only.
-
-@geindex -m (gnatbind)
-
-@item @code{-m`n'}
-
-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
-continues in this case. If the number of errors reaches this
-limit, then a message is output and the bind is abandoned.
-A value of zero means that no limit is enforced. The equal
-sign is optional.
-
-@geindex -minimal (gnatbind)
-
-@item @code{-minimal}
-
-Generate a binder file suitable for space-constrained applications. When
-active, binder-generated objects not required for program operation are no
-longer generated. `Warning:' this option comes with the following
-limitations:
-
-
-@itemize *
-
-@item 
-Starting the program’s execution in the debugger will cause it to
-stop at the start of the @code{main} function instead of the main subprogram.
-This can be worked around by manually inserting a breakpoint on that
-subprogram and resuming the program’s execution until reaching that breakpoint.
-
-@item 
-Programs using GNAT.Compiler_Version will not link.
-@end itemize
-
-@geindex -n (gnatbind)
-
-@item @code{-n}
-
-No main program.
-
-@geindex -nostdinc (gnatbind)
-
-@item @code{-nostdinc}
-
-Do not look for sources in the system default directory.
-
-@geindex -nostdlib (gnatbind)
-
-@item @code{-nostdlib}
-
-Do not look for library files in the system default directory.
-
-@geindex --RTS (gnatbind)
-
-@item @code{--RTS=`rts-path'}
-
-Specifies the default location of the run-time library. Same meaning as the
-equivalent @code{gnatmake} flag (@ref{ce,,Switches for gnatmake}).
-
-@geindex -o (gnatbind)
-
-@item @code{-o `file'}
-
-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.
-
-@geindex -O (gnatbind)
-
-@item @code{-O[=`filename']}
-
-Output object list (to standard output or to the named file).
-
-@geindex -p (gnatbind)
-
-@item @code{-p}
-
-Pessimistic (worst-case) elaboration order.
-
-@geindex -P (gnatbind)
-
-@item @code{-P}
-
-Generate binder file suitable for CodePeer.
-
-@geindex -R (gnatbind)
-
-@item @code{-R}
-
-Output closure source list, which includes all non-run-time units that are
-included in the bind.
-
-@geindex -Ra (gnatbind)
-
-@item @code{-Ra}
-
-Like @code{-R} but the list includes run-time units.
-
-@geindex -s (gnatbind)
-
-@item @code{-s}
-
-Require all source files to be present.
-
-@geindex -S (gnatbind)
-
-@item @code{-S`xxx'}
-
-Specifies the value to be used when detecting uninitialized scalar
-objects with pragma Initialize_Scalars.
-The @code{xxx} string specified with the switch is one of:
-
-
-@itemize *
-
-@item 
-@code{in} for an invalid value.
-
-If zero is invalid for the discrete type in question,
-then the scalar value is set to all zero bits.
-For signed discrete types, the largest possible negative value of
-the underlying scalar is set (i.e. a one bit followed by all zero bits).
-For unsigned discrete types, the underlying scalar value is set to all
-one bits. For floating-point types, a NaN value is set
-(see body of package System.Scalar_Values for exact values).
-
-@item 
-@code{lo} for low value.
-
-If zero is invalid for the discrete type in question,
-then the scalar value is set to all zero bits.
-For signed discrete types, the largest possible negative value of
-the underlying scalar is set (i.e. a one bit followed by all zero bits).
-For unsigned discrete types, the underlying scalar value is set to all
-zero bits. For floating-point, a small value is set
-(see body of package System.Scalar_Values for exact values).
-
-@item 
-@code{hi} for high value.
-
-If zero is invalid for the discrete type in question,
-then the scalar value is set to all one bits.
-For signed discrete types, the largest possible positive value of
-the underlying scalar is set (i.e. a zero bit followed by all one bits).
-For unsigned discrete types, the underlying scalar value is set to all
-one bits. For floating-point, a large value is set
-(see body of package System.Scalar_Values for exact values).
-
-@item 
-@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,
-then a 32-bit scalar value will be set to the bit patterm @code{16#BFBFBFBF#}.
-@end itemize
-
-@geindex GNAT_INIT_SCALARS
-
-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=@var{yy}}, where @code{yy} is one
-of @code{in/lo/hi/@var{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 @code{in} (invalid values).
-@end table
-
-@geindex -static (gnatbind)
-
-
-@table @asis
-
-@item @code{-static}
-
-Link against a static GNAT run-time.
-
-@geindex -shared (gnatbind)
-
-@item @code{-shared}
-
-Link against a shared GNAT run-time when available.
-
-@geindex -t (gnatbind)
-
-@item @code{-t}
-
-Tolerate time stamp and other consistency errors.
-
-@geindex -T (gnatbind)
-
-@item @code{-T`n'}
-
-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
-nonzero value will activate round-robin scheduling.
-
-A value of zero is treated specially. It turns off time
-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 @code{FIFO_Within_Priorities}.
-
-@geindex -u (gnatbind)
-
-@item @code{-u`n'}
-
-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
-platforms. (See @ref{113,,Dynamic Stack Usage Analysis} for details.)
-
-@geindex -v (gnatbind)
-
-@item @code{-v}
-
-Verbose mode. Write error messages, header, summary output to
-@code{stdout}.
-
-@geindex -V (gnatbind)
-
-@item @code{-V`key'=`value'}
-
-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
-@code{GNAT.Bind_Environment}.
-
-@geindex -w (gnatbind)
-
-@item @code{-w`x'}
-
-Warning mode; @code{x} = s/e for suppress/treat as error.
-
-@geindex -Wx (gnatbind)
-
-@item @code{-Wx`e'}
-
-Override default wide character encoding for standard Text_IO files.
-
-@geindex -x (gnatbind)
-
-@item @code{-x}
-
-Exclude source files (check object consistency only).
-
-@geindex -xdr (gnatbind)
-
-@item @code{-xdr}
-
-Use the target-independent XDR protocol for stream oriented attributes
-instead of the default implementation which is based on direct binary
-representations and is therefore target-and endianness-dependent.
-However it does not support 128-bit integer types and the exception
-@code{Ada.IO_Exceptions.Device_Error} is raised if any attempt is made
-at streaming 128-bit integer types with it.
-
-@geindex -Xnnn (gnatbind)
-
-@item @code{-X`nnn'}
-
-Set default exit status value, normally 0 for POSIX compliance.
-
-@geindex -y (gnatbind)
-
-@item @code{-y}
-
-Enable leap seconds support in @code{Ada.Calendar} and its children.
-
-@geindex -z (gnatbind)
-
-@item @code{-z}
-
-No main subprogram.
-@end table
-
-You may obtain this listing of switches by running @code{gnatbind} with
-no arguments.
-
-@menu
-* Consistency-Checking Modes:: 
-* Binder Error Message Control:: 
-* Elaboration Control:: 
-* Output Control:: 
-* Dynamic Allocation Control:: 
-* Binding with Non-Ada Main Programs:: 
-* Binding Programs with No Main Subprogram:: 
-
-@end menu
-
-@node Consistency-Checking Modes,Binder Error Message Control,,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat consistency-checking-modes}@anchor{114}@anchor{gnat_ugn/building_executable_programs_with_gnat id35}@anchor{115}
-@subsubsection Consistency-Checking Modes
-
-
-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.
-
-@quotation
-
-@geindex -s (gnatbind)
-@end quotation
-
-
-@table @asis
-
-@item @code{-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
-is simply ignored. If you specify this switch, a missing source
-file is an error.
-
-@geindex -Wx (gnatbind)
-
-@item @code{-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
-@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.
-
-@geindex -x (gnatbind)
-
-@item @code{-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
-the resulting program is self-consistent.
-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 @code{gnatmake} because in this
-case the checking against sources has already been performed by
-@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
-@anchor{gnat_ugn/building_executable_programs_with_gnat binder-error-message-control}@anchor{116}@anchor{gnat_ugn/building_executable_programs_with_gnat id36}@anchor{117}
-@subsubsection Binder Error Message Control
-
-
-The following switches provide control over the generation of error
-messages from the binder:
-
-@quotation
-
-@geindex -v (gnatbind)
-@end quotation
-
-
-@table @asis
-
-@item @code{-v}
-
-Verbose mode. In the normal mode, brief error messages are generated to
-@code{stderr}. If this switch is present, a header is written
-to @code{stdout} and any error messages are directed to @code{stdout}.
-All that is written to @code{stderr} is a brief summary message.
-
-@geindex -b (gnatbind)
-
-@item @code{-b}
-
-Generate brief error messages to @code{stderr} even if verbose mode is
-specified. This is relevant only when used with the
-@code{-v} switch.
-
-@geindex -m (gnatbind)
-
-@item @code{-m`n'}
-
-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`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 @code{gnatbind}.
-
-@geindex -ws (gnatbind)
-
-@geindex Warnings
-
-@item @code{-ws}
-
-Suppress all warning messages.
-
-@geindex -we (gnatbind)
-
-@item @code{-we}
-
-Treat any warning messages as fatal errors.
-
-@geindex -t (gnatbind)
-
-@geindex Time stamp checks
-@geindex in binder
-
-@geindex Binder consistency checks
-
-@geindex Consistency checks
-@geindex in binder
-
-@item @code{-t}
-
-The binder performs a number of consistency checks including:
-
-
-@itemize *
-
-@item 
-Check that time stamps of a given source unit are consistent
-
-@item 
-Check that checksums of a given source unit are consistent
-
-@item 
-Check that consistent versions of @code{GNAT} were used for compilation
-
-@item 
-Check consistency of configuration pragmas as required
-@end itemize
-
-Normally failure of such checks, in accordance with the consistency
-requirements of the Ada Reference Manual, causes error messages to be
-generated which abort the binder and prevent the output of a binder
-file and subsequent link to obtain an executable.
-
-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
-non-functional executable which has undefined semantics.
-
-@cartouche
-@quotation Note 
-This means that @code{-t} should be used only in unusual situations,
-with extreme care.
-@end quotation
-@end cartouche
-@end table
-
-@node Elaboration Control,Output Control,Binder Error Message Control,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat elaboration-control}@anchor{111}@anchor{gnat_ugn/building_executable_programs_with_gnat id37}@anchor{118}
-@subsubsection Elaboration Control
-
-
-The following switches provide additional control over the elaboration
-order. For further details see @ref{f,,Elaboration Order Handling in GNAT}.
-
-@geindex -f (gnatbind)
-
-
-@table @asis
-
-@item @code{-f`elab-order'}
-
-Force elaboration order.
-
-@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
-Some.Unit. Each pair of lines is taken to mean that there is an elaboration
-dependence of the second line on the first. For example, if the file
-contains:
-
-@example
-this (spec)
-this (body)
-that (spec)
-that (body)
-@end example
-
-then the spec of This will be elaborated before the body of This, and the
-body of This will be elaborated before the spec of That, and the spec of That
-will be elaborated before the body of That. The first and last of these three
-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 @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
-both elaborated before each other.
-
-If you later add “with That;” to the body of This, there will be a cycle, in
-which case you should erase either “this (body)” or “that (spec)” from the
-above forced elaboration order file.
-
-Blank lines and Ada-style comments are ignored. Unit names that do not exist
-in the program are ignored. Units in the GNAT predefined library are also
-ignored.
-@end table
-
-@geindex -p (gnatbind)
-
-
-@table @asis
-
-@item @code{-p}
-
-Pessimistic elaboration order
-
-This switch is only applicable to the pre-20.x legacy elaboration models.
-The post-20.x elaboration model uses a more informed approach of ordering
-the units.
-
-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
-@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 @code{-p} switch if dynamic
-elaboration checking is used (@code{-gnatE} switch used for compilation).
-This is because in the default static elaboration mode, all necessary
-@code{Elaborate} and @code{Elaborate_All} pragmas are implicitly inserted.
-These implicit pragmas are still respected by the binder in @code{-p}
-mode, so a safe elaboration order is assured.
-
-Note that @code{-p} is not intended for production use; it is more for
-debugging/experimental use.
-@end table
-
-@node Output Control,Dynamic Allocation Control,Elaboration Control,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat id38}@anchor{119}@anchor{gnat_ugn/building_executable_programs_with_gnat output-control}@anchor{11a}
-@subsubsection Output Control
-
-
-The following switches allow additional control over the output
-generated by the binder.
-
-@quotation
-
-@geindex -c (gnatbind)
-@end quotation
-
-
-@table @asis
-
-@item @code{-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.
-
-@geindex -e (gnatbind)
-
-@item @code{-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
-written to @code{stdout}.
-
-@geindex -h (gnatbind)
-
-@item @code{-h}
-
-Output usage information. The output is written to @code{stdout}.
-
-@geindex -K (gnatbind)
-
-@item @code{-K}
-
-Output linker options to @code{stdout}. Includes library search paths,
-contents of pragmas Ident and Linker_Options, and libraries added
-by @code{gnatbind}.
-
-@geindex -l (gnatbind)
-
-@item @code{-l}
-
-Output chosen elaboration order. The output is written to @code{stdout}.
-
-@geindex -O (gnatbind)
-
-@item @code{-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 @code{stdout}.
-This list includes the files explicitly supplied and referenced by the user
-as well as implicitly referenced run-time unit files. The latter are
-omitted if the corresponding units reside in shared libraries. The
-directory names for the run-time units depend on the system configuration.
-
-@geindex -o (gnatbind)
-
-@item @code{-o `file'}
-
-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
-the binder file.
-
-@geindex -r (gnatbind)
-
-@item @code{-r}
-
-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
-
-@node Dynamic Allocation Control,Binding with Non-Ada Main Programs,Output Control,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat dynamic-allocation-control}@anchor{112}@anchor{gnat_ugn/building_executable_programs_with_gnat id39}@anchor{11b}
-@subsubsection Dynamic Allocation Control
-
-
-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 @code{__gnat_malloc};
-explicit calls to @code{malloc} and related functions from the C
-run-time library are unaffected.
-
-
-@table @asis
-
-@item @code{-H32}
-
-Allocate memory on 32-bit heap
-
-@item @code{-H64}
-
-Allocate memory on 64-bit heap.  This is the default
-unless explicitly overridden by a @code{'Size} clause on the access type.
-@end table
-
-These switches are only effective on VMS platforms.
-
-@node Binding with Non-Ada Main Programs,Binding Programs with No Main Subprogram,Dynamic Allocation Control,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-non-ada-main-programs}@anchor{a0}@anchor{gnat_ugn/building_executable_programs_with_gnat id40}@anchor{11c}
-@subsubsection Binding with Non-Ada Main Programs
-
-
-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 @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{2c,,Mixed Language Programming}).
-The following switch is used in this situation:
-
-@quotation
-
-@geindex -n (gnatbind)
-@end quotation
-
-
-@table @asis
-
-@item @code{-n}
-
-No main program. The main program is not in Ada.
-@end table
-
-In this case, most of the functions of the binder are still required,
-but instead of generating a main program, the binder generates a file
-containing the following callable routines:
-
-@quotation
-
-@geindex adainit
-
-
-@table @asis
-
-@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 @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
-to be appropriate for Ada execution at the point where the first Ada
-subprogram is called. In particular, if the Ada code will do any
-floating-point operations, then the FPU must be setup in an appropriate
-manner. For the case of the x86, for example, full precision mode is
-required. The procedure GNAT.Float_Control.Reset may be used to ensure
-that the FPU is in the right state.
-@end table
-
-@geindex adafinal
-
-
-@table @asis
-
-@item @code{adafinal}
-
-You must call this routine to perform any library-level finalization
-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
-@end quotation
-
-@geindex -n (gnatbind)
-
-@geindex Binder
-@geindex multiple input files
-
-If the @code{-n} switch
-is given, more than one ALI file may appear on
-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
-`with' references. The reason it is necessary to be able to
-specify more than one ALI file is that a given program may invoke two or
-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 @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 @code{gnatlink}
-processing.
-
-Currently the GNAT run-time requires a FPU using 80 bits mode
-precision. Under targets where this is not the default it is required to
-call GNAT.Float_Control.Reset before using floating point numbers (this
-include float computation, float input and output) in the Ada code. A
-side effect is that this could be the wrong mode for the foreign code
-where floating point computation could be broken after this call.
-
-@node Binding Programs with No Main Subprogram,,Binding with Non-Ada Main Programs,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat binding-programs-with-no-main-subprogram}@anchor{11d}@anchor{gnat_ugn/building_executable_programs_with_gnat id41}@anchor{11e}
-@subsubsection Binding Programs with No Main Subprogram
-
-
-It is possible to have an Ada program which does not have a main
-subprogram. This program will call the elaboration routines of all the
-packages, then the finalization routines.
-
-The following switch is used to bind programs organized in this manner:
-
-@quotation
-
-@geindex -z (gnatbind)
-@end quotation
-
-
-@table @asis
-
-@item @code{-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
-consists of elaboration of these units in an appropriate order. Note
-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
-@code{-Wx} to override this default).
-@end table
-
-@node Command-Line Access,Search Paths for gnatbind,Switches for gnatbind,Binding with gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat command-line-access}@anchor{11f}@anchor{gnat_ugn/building_executable_programs_with_gnat id42}@anchor{120}
-@subsection Command-Line Access
-
-
-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
-
-@example
-int gnat_argc;
-char **gnat_argv;
-@end example
-
-@geindex gnat_argv
-
-@geindex gnat_argc
-
-are declared in one of the GNAT library routines. These variables must
-be set from the actual @code{argc} and @code{argv} values passed to the
-main program. With no `n' present, @code{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
-@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 id43}@anchor{121}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-for-gnatbind}@anchor{76}
-@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 @code{gcc}
-(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). For ALI files the
-directories searched are:
-
-
-@itemize *
-
-@item 
-The directory containing the ALI file named in the command line, unless
-the switch @code{-I-} is specified.
-
-@item 
-All directories specified by @code{-I}
-switches on the @code{gnatbind}
-command line, in the order given.
-
-@geindex ADA_PRJ_OBJECTS_FILE
-
-@item 
-Each of the directories listed in the text file whose name is given
-by the 
-@geindex ADA_PRJ_OBJECTS_FILE
-@geindex environment variable; ADA_PRJ_OBJECTS_FILE
-@code{ADA_PRJ_OBJECTS_FILE} environment variable.
-
-@geindex ADA_PRJ_OBJECTS_FILE
-@geindex environment variable; ADA_PRJ_OBJECTS_FILE
-@code{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the gnat
-driver when project files are used. It should not normally be set
-by other means.
-
-@geindex ADA_OBJECTS_PATH
-
-@item 
-Each of the directories listed in the value of the
-@geindex ADA_OBJECTS_PATH
-@geindex environment variable; ADA_OBJECTS_PATH
-@code{ADA_OBJECTS_PATH} environment variable.
-Construct this value
-exactly as the 
-@geindex PATH
-@geindex environment variable; PATH
-@code{PATH} environment variable: a list of directory
-names separated by colons (semicolons when working with the NT version
-of GNAT).
-
-@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 @code{-nostdlib} is
-specified. See @ref{72,,Installing a library}
-@end itemize
-
-@geindex -I (gnatbind)
-
-@geindex -aI (gnatbind)
-
-@geindex -aO (gnatbind)
-
-In the binder the switch @code{-I}
-is used to specify both source and
-library file paths. Use @code{-aI}
-instead if you want to specify
-source paths only, and @code{-aO}
-if you want to specify library paths
-only. This means that for the binder
-@code{-I`dir'} is equivalent to
-@code{-aI`dir'}
-@code{-aO``dir'}.
-The binder generates the bind file (a C language source file) in the
-current working directory.
-
-@geindex Ada
-
-@geindex System
-
-@geindex Interfaces
-
-@geindex GNAT
-
-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
-needed by the compiler and are kept together in one directory. The ALI
-files and object files generated by compiling the RTL are needed by the
-binder and the linker and are kept together in one directory, typically
-different from the directory containing the sources. 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.
-
-Besides simplifying access to the RTL, a major use of search paths is
-in compiling sources from multiple directories. This can make
-development environments much more flexible.
-
-@node Examples of gnatbind Usage,,Search Paths for gnatbind,Binding with gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatbind-usage}@anchor{122}@anchor{gnat_ugn/building_executable_programs_with_gnat id44}@anchor{123}
-@subsection Examples of @code{gnatbind} Usage
-
-
-Here are some examples of @code{gnatbind} invocations:
-
-@quotation
-
-@example
-gnatbind hello
-@end example
-
-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.
-
-@example
-gnatbind hello -o mainprog.adb
-@end example
-
-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
-spec. Note that if this option is used, then linking must be done manually,
-since gnatlink will not be able to find the generated file.
-@end quotation
-
-@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{124}@anchor{gnat_ugn/building_executable_programs_with_gnat linking-with-gnatlink}@anchor{c9}
-@section Linking with @code{gnatlink}
-
-
-@geindex gnatlink
-
-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 @code{gcc} command)
-with a correct list of object files and library references.
-@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 @code{gnatbind} to determine this list.
-
-@menu
-* Running gnatlink:: 
-* Switches for gnatlink:: 
-
-@end menu
-
-@node Running gnatlink,Switches for gnatlink,,Linking with gnatlink
-@anchor{gnat_ugn/building_executable_programs_with_gnat id46}@anchor{125}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatlink}@anchor{126}
-@subsection Running @code{gnatlink}
-
-
-The form of the @code{gnatlink} command is
-
-@example
-$ gnatlink [ switches ] mainprog [.ali]
-           [ non-Ada objects ] [ linker options ]
-@end example
-
-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.
-Any file name @code{F} without the @code{.ali}
-extension will be taken as the main @code{ALI} file if a file exists
-whose name is the concatenation of @code{F} and @code{.ali}.
-
-@code{mainprog.ali} references the ALI file of the main program.
-The @code{.ali} extension of this file can be omitted. From this
-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 @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 @code{Import} pragmas in any Ada units.
-
-@code{linker options} is an optional list of linker specific
-switches.
-The default linker called by gnatlink is @code{gcc} which in
-turn calls the appropriate system linker.
-
-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 @code{-lmy_lib} or
-@code{-Ldir} can be added as is.
-For options that are not recognized by
-@code{gcc} as linker options, use the @code{gcc} switches
-@code{-Xlinker} or @code{-Wl,}.
-
-Refer to the GCC documentation for
-details.
-
-Here is an example showing how to generate a linker map:
-
-@example
-$ gnatlink my_prog -Wl,-Map,MAPFILE
-@end example
-
-Using @code{linker options} it is possible to set the program stack and
-heap size.
-See @ref{127,,Setting Stack Size from gnatlink} and
-@ref{128,,Setting Heap Size from gnatlink}.
-
-@code{gnatlink} determines the list of objects required by the Ada
-program and prepends them to the list of objects passed to the linker.
-@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{129}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatlink}@anchor{12a}
-@subsection Switches for @code{gnatlink}
-
-
-The following switches are available with the @code{gnatlink} utility:
-
-@geindex --version (gnatlink)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display Copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatlink)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
-
-@geindex Command line length
-
-@geindex -f (gnatlink)
-
-
-@table @asis
-
-@item @code{-f}
-
-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 @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.
-@end table
-
-@geindex Debugging information
-@geindex including
-
-@geindex -g (gnatlink)
-
-
-@table @asis
-
-@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 @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 @code{-g}, the binder removes these files by default.
-@end table
-
-@geindex -n (gnatlink)
-
-
-@table @asis
-
-@item @code{-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.
-@end table
-
-@geindex -v (gnatlink)
-
-
-@table @asis
-
-@item @code{-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
-to see what set of object files are being used in the link step.
-@end table
-
-@geindex -v -v (gnatlink)
-
-
-@table @asis
-
-@item @code{-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.
-@end table
-
-@geindex -o (gnatlink)
-
-
-@table @asis
-
-@item @code{-o `exec-name'}
-
-@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, @code{gnatlink try.ali} creates
-an executable called @code{try}.
-@end table
-
-@geindex -B (gnatlink)
-
-
-@table @asis
-
-@item @code{-B`dir'}
-
-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 @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)
-
-
-@table @asis
-
-@item @code{-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”.
-@end table
-
-@geindex -M= (gnatlink)
-
-
-@table @asis
-
-@item @code{-M=`mapfile'}
-
-When linking an executable, create a map file. The name of the map file is
-@code{mapfile}.
-@end table
-
-@geindex --GCC=compiler_name (gnatlink)
-
-
-@table @asis
-
-@item @code{--GCC=`compiler_name'}
-
-Program used for compiling the binder file. The default is
-@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 @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 @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"}.
-@end table
-
-@geindex --LINK= (gnatlink)
-
-
-@table @asis
-
-@item @code{--LINK=`name'}
-
-@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 @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
-switch.
-@end table
-
-@node Using the GNU make Utility,,Linking with gnatlink,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat id48}@anchor{12b}@anchor{gnat_ugn/building_executable_programs_with_gnat using-the-gnu-make-utility}@anchor{70}
-@section Using the GNU @code{make} Utility
-
-
-@geindex make (GNU)
-@geindex 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
-@code{gnatmake} utility (@ref{c6,,Building with gnatmake}).
-
-All the examples in this section are specific to the GNU version of
-make. Although @code{make} is a standard utility, and the basic language
-is the same, these examples use some advanced features found only in
-@code{GNU make}.
-
-@menu
-* Using gnatmake in a Makefile:: 
-* Automatically Creating a List of Directories:: 
-* Generating the Command Line Switches:: 
-* Overcoming Command Line Length Limits:: 
-
-@end menu
-
-@node Using gnatmake in a Makefile,Automatically Creating a List of Directories,,Using the GNU make Utility
-@anchor{gnat_ugn/building_executable_programs_with_gnat id49}@anchor{12c}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gnatmake-in-a-makefile}@anchor{12d}
-@subsection Using gnatmake in a Makefile
-
-
-@c index makefile (GNU make)
-
-Complex project organizations can be handled in a very powerful way by
-using GNU make combined with gnatmake. For instance, here is a Makefile
-which allows you to build each subsystem of a big project into a separate
-shared library. Such a makefile allows you to significantly reduce the link
-time of very big applications while maintaining full coherence at
-each step of the build process.
-
-The list of dependencies are handled automatically by
-@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
-create the list of directories
-(@ref{12e,,Automatically Creating a List of Directories})
-which might help you in case your project has a lot of subdirectories.
-
-@example
-## This Makefile is intended to be used with the following directory
-## configuration:
-##  - The sources are split into a series of csc (computer software components)
-##    Each of these csc is put in its own directory.
-##    Their name are referenced by the directory names.
-##    They will be compiled into shared library (although this would also work
-##    with static libraries)
-##  - The main program (and possibly other packages that do not belong to any
-##    csc) is put in the top level directory (where the Makefile is).
-##       toplevel_dir __ first_csc  (sources) __ lib (will contain the library)
-##                    \\_ second_csc (sources) __ lib (will contain the library)
-##                    \\_ ...
-## Although this Makefile is build for shared library, it is easy to modify
-## to build partial link objects instead (modify the lines with -shared and
-## gnatlink below)
-##
-## With this makefile, you can change any file in the system or add any new
-## file, and everything will be recompiled correctly (only the relevant shared
-## objects will be recompiled, and the main program will be re-linked).
-
-# The list of computer software component for your project. This might be
-# generated automatically.
-CSC_LIST=aa bb cc
-
-# Name of the main program (no extension)
-MAIN=main
-
-# If we need to build objects with -fPIC, uncomment the following line
-#NEED_FPIC=-fPIC
-
-# The following variable should give the directory containing libgnat.so
-# You can get this directory through 'gnatls -v'. This is usually the last
-# directory in the Object_Path.
-GLIB=...
-
-# The directories for the libraries
-# (This macro expands the list of CSC to the list of shared libraries, you
-# could simply use the expanded form:
-# LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
-LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@}
-
-$@{MAIN@}: objects $@{LIB_DIR@}
-    gnatbind $@{MAIN@} $@{CSC_LIST:%=-aO%/lib@} -shared
-    gnatlink $@{MAIN@} $@{CSC_LIST:%=-l%@}
-
-objects::
-    # recompile the sources
-    gnatmake -c -i $@{MAIN@}.adb $@{NEED_FPIC@} $@{CSC_LIST:%=-I%@}
-
-# Note: In a future version of GNAT, the following commands will be simplified
-# by a new tool, gnatmlib
-$@{LIB_DIR@}:
-    mkdir -p $@{dir $@@ @}
-    cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat
-    cd $@{dir $@@ @} && cp -f ../*.ali .
-
-# The dependencies for the modules
-# Note that we have to force the expansion of *.o, since in some cases
-# make won't be able to do it itself.
-aa/lib/libaa.so: $@{wildcard aa/*.o@}
-bb/lib/libbb.so: $@{wildcard bb/*.o@}
-cc/lib/libcc.so: $@{wildcard cc/*.o@}
-
-# Make sure all of the shared libraries are in the path before starting the
-# program
-run::
-    LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./$@{MAIN@}
-
-clean::
-    $@{RM@} -rf $@{CSC_LIST:%=%/lib@}
-    $@{RM@} $@{CSC_LIST:%=%/*.ali@}
-    $@{RM@} $@{CSC_LIST:%=%/*.o@}
-    $@{RM@} *.o *.ali $@{MAIN@}
-@end example
-
-@node Automatically Creating a List of Directories,Generating the Command Line Switches,Using gnatmake in a Makefile,Using the GNU make Utility
-@anchor{gnat_ugn/building_executable_programs_with_gnat automatically-creating-a-list-of-directories}@anchor{12e}@anchor{gnat_ugn/building_executable_programs_with_gnat id50}@anchor{12f}
-@subsection Automatically Creating a List of Directories
-
-
-In most makefiles, you will have to specify a list of directories, and
-store it in a variable. For small projects, it is often easier to
-specify each of them by hand, since you then have full control over what
-is the proper order for these directories, which ones should be
-included.
-
-However, in larger projects, which might involve hundreds of
-subdirectories, it might be more convenient to generate this list
-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 @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 @code{find}, which is standard on all Unix systems. All
-the directories found under a given root directory will be added to the
-list.
-
-@example
-# The examples below are based on the following directory hierarchy:
-# All the directories can contain any number of files
-# ROOT_DIRECTORY ->  a  ->  aa  ->  aaa
-#                       ->  ab
-#                       ->  ac
-#                ->  b  ->  ba  ->  baa
-#                       ->  bb
-#                       ->  bc
-# This Makefile creates a variable called DIRS, that can be reused any time
-# you need this list (see the other examples in this section)
-
-# The root of your project's directory hierarchy
-ROOT_DIRECTORY=.
-
-####
-# First method: specify explicitly the list of directories
-# This allows you to specify any subset of all the directories you need.
-####
-
-DIRS := a/aa/ a/ab/ b/ba/
-
-####
-# Second method: use wildcards
-# 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 `@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/
-####
-
-DIRS := $@{sort $@{dir $@{wildcard $@{ROOT_DIRECTORY@}/*/
-                    $@{ROOT_DIRECTORY@}/*/*/@}@}@}
-
-####
-# Third method: use an external program
-# This command is much faster if run on local disks, avoiding NFS slowdowns.
-# This is the most complete command: it sets DIRs to the following value:
-# DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
-####
-
-DIRS := $@{shell find $@{ROOT_DIRECTORY@} -type d -print@}
-@end example
-
-@node Generating the Command Line Switches,Overcoming Command Line Length Limits,Automatically Creating a List of Directories,Using the GNU make Utility
-@anchor{gnat_ugn/building_executable_programs_with_gnat generating-the-command-line-switches}@anchor{130}@anchor{gnat_ugn/building_executable_programs_with_gnat id51}@anchor{131}
-@subsection Generating the Command Line Switches
-
-
-Once you have created the list of directories as explained in the
-previous section (@ref{12e,,Automatically Creating a List of Directories}),
-you can easily generate the command line arguments to pass to gnatmake.
-
-For the sake of completeness, this example assumes that the source path
-is not the same as the object path, and that you have two separate lists
-of directories.
-
-@example
-# see "Automatically creating a list of directories" to create
-# these variables
-SOURCE_DIRS=
-OBJECT_DIRS=
-
-GNATMAKE_SWITCHES := $@{patsubst %,-aI%,$@{SOURCE_DIRS@}@}
-GNATMAKE_SWITCHES += $@{patsubst %,-aO%,$@{OBJECT_DIRS@}@}
-
-all:
-        gnatmake $@{GNATMAKE_SWITCHES@} main_unit
-@end example
-
-@node Overcoming Command Line Length Limits,,Generating the Command Line Switches,Using the GNU make Utility
-@anchor{gnat_ugn/building_executable_programs_with_gnat id52}@anchor{132}@anchor{gnat_ugn/building_executable_programs_with_gnat overcoming-command-line-length-limits}@anchor{133}
-@subsection Overcoming Command Line Length Limits
-
-
-One problem that might be encountered on big projects is that many
-operating systems limit the length of the command line. It is thus hard to give
-gnatmake the list of source and object directories.
-
-This example shows how you can set up environment variables, which will
-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).
-
-It assumes that you have created a list of directories in your Makefile,
-using one of the methods presented in
-@ref{12e,,Automatically Creating a List of Directories}.
-For the sake of completeness, we assume that the object
-path (where the ALI files are found) is different from the sources patch.
-
-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 @code{make}. This way we overcome the standard
-make behavior which is to expand the variables only when they are
-actually used.
-
-On Windows, if you are using the standard Windows command shell, you must
-replace colons with semicolons in the assignments to these variables.
-
-@example
-# In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
-# This is the same thing as putting the -I arguments on the command line.
-# (the equivalent of using -aI on the command line would be to define
-#  only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH).
-# You can of course have different values for these variables.
-#
-# Note also that we need to keep the previous values of these variables, since
-# they might have been set before running 'make' to specify where the GNAT
-# library is installed.
-
-# see "Automatically creating a list of directories" to create these
-# variables
-SOURCE_DIRS=
-OBJECT_DIRS=
-
-empty:=
-space:=$@{empty@} $@{empty@}
-SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@}
-OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@}
-ADA_INCLUDE_PATH += $@{SOURCE_LIST@}
-ADA_OBJECTS_PATH += $@{OBJECT_LIST@}
-export ADA_INCLUDE_PATH
-export ADA_OBJECTS_PATH
-
-all:
-        gnatmake main_unit
-@end example
-
-@node GNAT Utility Programs,GNAT and Program Execution,Building Executable Programs with GNAT,Top
-@anchor{gnat_ugn/gnat_utility_programs doc}@anchor{134}@anchor{gnat_ugn/gnat_utility_programs gnat-utility-programs}@anchor{b}@anchor{gnat_ugn/gnat_utility_programs id1}@anchor{135}
-@chapter GNAT Utility Programs
-
-
-This chapter describes a number of utility programs:
-
-
-
-@itemize *
-
-@item 
-@ref{136,,The File Cleanup Utility gnatclean}
-
-@item 
-@ref{137,,The GNAT Library Browser gnatls}
-@end itemize
-
-Other GNAT utilities are described elsewhere in this manual:
-
-
-@itemize *
-
-@item 
-@ref{42,,Handling Arbitrary File Naming Conventions with gnatname}
-
-@item 
-@ref{4c,,File Name Krunching with gnatkr}
-
-@item 
-@ref{1d,,Renaming Files with gnatchop}
-
-@item 
-@ref{8f,,Preprocessing with gnatprep}
-@end itemize
-
-@menu
-* The File Cleanup Utility gnatclean:: 
-* The GNAT Library Browser gnatls:: 
-
-@end menu
-
-@node The File Cleanup Utility gnatclean,The GNAT Library Browser gnatls,,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs id2}@anchor{138}@anchor{gnat_ugn/gnat_utility_programs the-file-cleanup-utility-gnatclean}@anchor{136}
-@section The File Cleanup Utility @code{gnatclean}
-
-
-@geindex File cleanup tool
-
-@geindex gnatclean
-
-@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.
-
-@menu
-* Running gnatclean:: 
-* Switches for gnatclean:: 
-
-@end menu
-
-@node Running gnatclean,Switches for gnatclean,,The File Cleanup Utility gnatclean
-@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{139}@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{13a}
-@subsection Running @code{gnatclean}
-
-
-The @code{gnatclean} command has the form:
-
-@quotation
-
-@example
-$ gnatclean switches names
-@end example
-@end quotation
-
-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 @code{names} may be completely omitted.
-
-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
-@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{13b}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{13c}
-@subsection Switches for @code{gnatclean}
-
-
-@code{gnatclean} recognizes the following switches:
-
-@geindex --version (gnatclean)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatclean)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-
-@item @code{--subdirs=`subdir'}
-
-Actual object directory of each project file is the subdirectory subdir of the
-object directory specified or defaulted in the project file.
-
-@item @code{--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.
-@end table
-
-@geindex -c (gnatclean)
-
-
-@table @asis
-
-@item @code{-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.
-@end table
-
-@geindex -D (gnatclean)
-
-
-@table @asis
-
-@item @code{-D `dir'}
-
-Indicate that ALI and object files should normally be found in directory @code{dir}.
-@end table
-
-@geindex -F (gnatclean)
-
-
-@table @asis
-
-@item @code{-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
-file, rather than its simple file name.
-@end table
-
-@geindex -h (gnatclean)
-
-
-@table @asis
-
-@item @code{-h}
-
-Output a message explaining the usage of @code{gnatclean}.
-@end table
-
-@geindex -n (gnatclean)
-
-
-@table @asis
-
-@item @code{-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.
-@end table
-
-@geindex -P (gnatclean)
-
-
-@table @asis
-
-@item @code{-P`project'}
-
-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
-on the command line.
-@end table
-
-@geindex -q (gnatclean)
-
-
-@table @asis
-
-@item @code{-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).
-@end table
-
-@geindex -r (gnatclean)
-
-
-@table @asis
-
-@item @code{-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
-deleted. This switch has no effect if no project file is specified.
-@end table
-
-@geindex -v (gnatclean)
-
-
-@table @asis
-
-@item @code{-v}
-
-Verbose mode.
-@end table
-
-@geindex -vP (gnatclean)
-
-
-@table @asis
-
-@item @code{-vP`x'}
-
-Indicates the verbosity of the parsing of GNAT project files.
-@ref{cf,,Switches Related to Project Files}.
-@end table
-
-@geindex -X (gnatclean)
-
-
-@table @asis
-
-@item @code{-X`name'=`value'}
-
-Indicates that external variable @code{name} has the value @code{value}.
-The Project Manager will use this value for occurrences of
-@code{external(name)} when parsing the project file.
-See @ref{cf,,Switches Related to Project Files}.
-@end table
-
-@geindex -aO (gnatclean)
-
-
-@table @asis
-
-@item @code{-aO`dir'}
-
-When searching for ALI and object files, look in directory @code{dir}.
-@end table
-
-@geindex -I (gnatclean)
-
-
-@table @asis
-
-@item @code{-I`dir'}
-
-Equivalent to @code{-aO`dir'}.
-@end table
-
-@geindex -I- (gnatclean)
-
-@geindex Source files
-@geindex suppressing search
-
-
-@table @asis
-
-@item @code{-I-}
-
-Do not look for ALI or object files in the directory
-where @code{gnatclean} was invoked.
-@end table
-
-@node The GNAT Library Browser gnatls,,The File Cleanup Utility gnatclean,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{13d}@anchor{gnat_ugn/gnat_utility_programs the-gnat-library-browser-gnatls}@anchor{137}
-@section The GNAT Library Browser @code{gnatls}
-
-
-@geindex Library browser
-
-@geindex gnatls
-
-@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.
-
-@menu
-* Running gnatls:: 
-* Switches for gnatls:: 
-* Example of gnatls Usage:: 
-
-@end menu
-
-@node Running gnatls,Switches for gnatls,,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{13e}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{13f}
-@subsection Running @code{gnatls}
-
-
-The @code{gnatls} command has the form
-
-@quotation
-
-@example
-$ gnatls switches object_or_ali_file
-@end example
-@end quotation
-
-The main argument is the list of object or @code{ali} files
-(see @ref{28,,The Ada Library Information Files})
-for which information is requested.
-
-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
-column gives the status of the source and the fourth column gives the
-full path of the source representing this unit.
-Here is a simple example of use:
-
-@quotation
-
-@example
-$ gnatls *.o
-./demo1.o            demo1            DIF demo1.adb
-./demo2.o            demo2             OK demo2.adb
-./hello.o            h1                OK hello.adb
-./instr-child.o      instr.child      MOK instr-child.adb
-./instr.o            instr             OK instr.adb
-./tef.o              tef              DIF tef.adb
-./text_io_example.o  text_io_example   OK text_io_example.adb
-./tgef.o             tgef             DIF tgef.adb
-@end example
-@end quotation
-
-The first line can be interpreted as follows: the main unit which is
-contained in
-object file @code{demo1.o} is demo1, whose main source is in
-@code{demo1.adb}. Furthermore, the version of the source used for the
-compilation of demo1 has been modified (DIF). Each source file has a status
-qualifier which can be:
-
-
-@table @asis
-
-@item `OK (unchanged)'
-
-The version of the source file used for the compilation of the
-specified unit corresponds exactly to the actual source file.
-
-@item `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 option
-@code{-m} (minimal recompilation), a file marked
-MOK will not be recompiled.
-
-@item `DIF (modified)'
-
-No version of the source found on the path corresponds to the source
-used to build this object.
-
-@item `??? (file not found)'
-
-No source file was found for this unit.
-
-@item `HID (hidden,  unchanged version not first on PATH)'
-
-The version of the source that corresponds exactly to the source used
-for compilation has been found on the path but it is hidden by another
-version of the same source that has been modified.
-@end table
-
-@node Switches for gnatls,Example of gnatls Usage,Running gnatls,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id7}@anchor{140}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{141}
-@subsection Switches for @code{gnatls}
-
-
-@code{gnatls} recognizes the following switches:
-
-@geindex --version (gnatls)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatls)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
-
-@geindex -a (gnatls)
-
-
-@table @asis
-
-@item @code{-a}
-
-Consider all units, including those of the predefined Ada library.
-Especially useful with @code{-d}.
-@end table
-
-@geindex -d (gnatls)
-
-
-@table @asis
-
-@item @code{-d}
-
-List sources from which specified units depend on.
-@end table
-
-@geindex -h (gnatls)
-
-
-@table @asis
-
-@item @code{-h}
-
-Output the list of options.
-@end table
-
-@geindex -o (gnatls)
-
-
-@table @asis
-
-@item @code{-o}
-
-Only output information about object files.
-@end table
-
-@geindex -s (gnatls)
-
-
-@table @asis
-
-@item @code{-s}
-
-Only output information about source files.
-@end table
-
-@geindex -u (gnatls)
-
-
-@table @asis
-
-@item @code{-u}
-
-Only output information about compilation units.
-@end table
-
-@geindex -files (gnatls)
-
-
-@table @asis
-
-@item @code{-files=`file'}
-
-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
-
-@geindex -aO (gnatls)
-
-@geindex -aI (gnatls)
-
-@geindex -I (gnatls)
-
-@geindex -I- (gnatls)
-
-
-@table @asis
-
-@item @code{-aO`dir'}, @code{-aI`dir'}, @code{-I`dir'}, @code{-I-}, @code{-nostdinc}
-
-Source path manipulation. Same meaning as the equivalent @code{gnatmake}
-flags (@ref{ce,,Switches for gnatmake}).
-@end table
-
-@geindex -aP (gnatls)
-
-
-@table @asis
-
-@item @code{-aP`dir'}
-
-Add @code{dir} at the beginning of the project search dir.
-@end table
-
-@geindex --RTS (gnatls)
-
-
-@table @asis
-
-@item @code{--RTS=`rts-path'}
-
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (@ref{ce,,Switches for gnatmake}).
-@end table
-
-@geindex -v (gnatls)
-
-
-@table @asis
-
-@item @code{-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
-characteristics such as:
-
-
-@itemize *
-
-@item 
-`Preelaborable': The unit is preelaborable in the Ada sense.
-
-@item 
-`No_Elab_Code':  No elaboration code has been produced by the compiler for this unit.
-
-@item 
-`Pure': The unit is pure in the Ada sense.
-
-@item 
-`Elaborate_Body': The unit contains a pragma Elaborate_Body.
-
-@item 
-`Remote_Types': The unit contains a pragma Remote_Types.
-
-@item 
-`Shared_Passive': The unit contains a pragma Shared_Passive.
-
-@item 
-`Predefined': This unit is part of the predefined environment and cannot be modified
-by the user.
-
-@item 
-`Remote_Call_Interface': The unit contains a pragma Remote_Call_Interface.
-@end itemize
-@end table
-
-@node Example of gnatls Usage,,Switches for gnatls,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{142}@anchor{gnat_ugn/gnat_utility_programs id8}@anchor{143}
-@subsection Example of @code{gnatls} Usage
-
-
-Example of using the verbose switch. Note how the source and
-object paths are affected by the -I switch.
-
-@quotation
-
-@example
-$ gnatls -v -I.. demo1.o
-
-GNATLS 5.03w (20041123-34)
-Copyright 1997-2004 Free Software Foundation, Inc.
-
-Source Search Path:
-   <Current_Directory>
-   ../
-   /home/comar/local/adainclude/
-
-Object Search Path:
-   <Current_Directory>
-   ../
-   /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/
-
-Project Search Path:
-   <Current_Directory>
-   /home/comar/local/lib/gnat/
-
-./demo1.o
-   Unit =>
-     Name   => demo1
-     Kind   => subprogram body
-     Flags  => No_Elab_Code
-     Source => demo1.adb    modified
-@end example
-@end quotation
-
-The following is an example of use of the dependency list.
-Note the use of the -s switch
-which gives a straight list of source files. This can be useful for
-building specialized scripts.
-
-@quotation
-
-@example
-$ gnatls -d demo2.o
-./demo2.o   demo2        OK demo2.adb
-                         OK gen_list.ads
-                         OK gen_list.adb
-                         OK instr.ads
-                         OK instr-child.ads
-
-$ gnatls -d -s -a demo1.o
-demo1.adb
-/home/comar/local/adainclude/ada.ads
-/home/comar/local/adainclude/a-finali.ads
-/home/comar/local/adainclude/a-filico.ads
-/home/comar/local/adainclude/a-stream.ads
-/home/comar/local/adainclude/a-tags.ads
-gen_list.ads
-gen_list.adb
-/home/comar/local/adainclude/gnat.ads
-/home/comar/local/adainclude/g-io.ads
-instr.ads
-/home/comar/local/adainclude/system.ads
-/home/comar/local/adainclude/s-exctab.ads
-/home/comar/local/adainclude/s-finimp.ads
-/home/comar/local/adainclude/s-finroo.ads
-/home/comar/local/adainclude/s-secsta.ads
-/home/comar/local/adainclude/s-stalib.ads
-/home/comar/local/adainclude/s-stoele.ads
-/home/comar/local/adainclude/s-stratt.ads
-/home/comar/local/adainclude/s-tasoli.ads
-/home/comar/local/adainclude/s-unstyp.ads
-/home/comar/local/adainclude/unchconv.ads
-@end example
-@end quotation
-
-
-
-
-
-
-@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
-
-@node GNAT and Program Execution,Platform-Specific Information,GNAT Utility Programs,Top
-@anchor{gnat_ugn/gnat_and_program_execution doc}@anchor{144}@anchor{gnat_ugn/gnat_and_program_execution gnat-and-program-execution}@anchor{c}@anchor{gnat_ugn/gnat_and_program_execution id1}@anchor{145}
-@chapter GNAT and Program Execution
-
-
-This chapter covers several topics:
-
-
-@itemize *
-
-@item 
-@ref{146,,Running and Debugging Ada Programs}
-
-@item 
-@ref{147,,Profiling}
-
-@item 
-@ref{148,,Improving Performance}
-
-@item 
-@ref{149,,Overflow Check Handling in GNAT}
-
-@item 
-@ref{14a,,Performing Dimensionality Analysis in GNAT}
-
-@item 
-@ref{14b,,Stack Related Facilities}
-
-@item 
-@ref{14c,,Memory Management Issues}
-@end itemize
-
-@menu
-* Running and Debugging Ada Programs:: 
-* Profiling:: 
-* Improving Performance:: 
-* Overflow Check Handling in GNAT:: 
-* Performing Dimensionality Analysis in GNAT:: 
-* Stack Related Facilities:: 
-* Memory Management Issues:: 
-
-@end menu
-
-@node Running and Debugging Ada Programs,Profiling,,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id2}@anchor{146}@anchor{gnat_ugn/gnat_and_program_execution running-and-debugging-ada-programs}@anchor{14d}
-@section Running and Debugging Ada Programs
-
-
-@geindex Debugging
-
-This section discusses how to debug Ada programs.
-
-An incorrect Ada program may be handled in three ways by the GNAT compiler:
-
-
-@itemize *
-
-@item 
-The illegality may be a violation of the static semantics of Ada. In
-that case GNAT diagnoses the constructs in the program that are illegal.
-It is then a straightforward matter for the user to modify those parts of
-the program.
-
-@item 
-The illegality may be a violation of the dynamic semantics of Ada. In
-that case the program compiles and executes, but may generate incorrect
-results, or may terminate abnormally with some exception.
-
-@item 
-When presented with a program that contains convoluted errors, GNAT
-itself may terminate abnormally without providing full diagnostics on
-the incorrect user program.
-@end itemize
-
-@geindex Debugger
-
-@geindex gdb
-
-@menu
-* The GNAT Debugger GDB:: 
-* Running GDB:: 
-* Introduction to GDB Commands:: 
-* Using Ada Expressions:: 
-* Calling User-Defined Subprograms:: 
-* Using the next Command in a Function:: 
-* Stopping When Ada Exceptions Are Raised:: 
-* Ada Tasks:: 
-* Debugging Generic Units:: 
-* Remote Debugging with gdbserver:: 
-* GNAT Abnormal Termination or Failure to Terminate:: 
-* Naming Conventions for GNAT Source Files:: 
-* Getting Internal Debugging Information:: 
-* Stack Traceback:: 
-* Pretty-Printers for the GNAT runtime:: 
-
-@end menu
-
-@node The GNAT Debugger GDB,Running GDB,,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id3}@anchor{14e}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debugger-gdb}@anchor{14f}
-@subsection The GNAT Debugger GDB
-
-
-@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 @code{GDB} are Ada-aware and can handle
-complex Ada data structures.
-
-See @cite{Debugging with GDB},
-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 @code{GDB}.
-
-When GNAT programs are compiled, the compiler optionally writes debugging
-information into the generated object file, including information on
-line numbers, and on declared types and variables. This information is
-separate from the generated code. It makes the object files considerably
-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
-@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.
-
-The debugging information is written in standard system formats that
-are used by many tools, including debuggers and profilers. The format
-of the information is typically designed to describe C types and
-semantics, but GNAT implements a translation scheme which allows full
-details about Ada types and variables to be encoded into these
-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 @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 program. Again, this process significantly increases the size of
-the generated executable file, but it does not increase the size of
-the executable program itself. Furthermore, if this program is run in
-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 @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 @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, @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.
-
-@node Running GDB,Introduction to GDB Commands,The GNAT Debugger GDB,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id4}@anchor{150}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{151}
-@subsection Running GDB
-
-
-This section describes how to initiate the debugger.
-
-The debugger can be launched from a @code{GNAT Studio} menu or
-directly from the command line. The description below covers the latter use.
-All the commands shown can be used in the @code{GNAT Studio} debug console window,
-but there are usually more GUI-based ways to achieve the same effect.
-
-The command to run @code{GDB} is
-
-@quotation
-
-@example
-$ gdb program
-@end example
-@end quotation
-
-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 @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 @code{GDB}.
-
-@node Introduction to GDB Commands,Using Ada Expressions,Running GDB,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{152}@anchor{gnat_ugn/gnat_and_program_execution introduction-to-gdb-commands}@anchor{153}
-@subsection Introduction to GDB 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 `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 @code{GDB} is about. You should create
-a simple program with debugging information and experiment with the use of
-these @code{GDB} commands on the program as you read through the
-following section.
-
-
-@itemize *
-
-@item 
-
-@table @asis
-
-@item @code{set args @var{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 @code{set args}
-command is not needed if the program does not require arguments.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{run}
-
-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
-restart.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{breakpoint @var{location}}
-
-The breakpoint command sets a breakpoint, that is to say a point at which
-execution will halt and @code{GDB} will await further
-commands. `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 @code{GDB} signals that the breakpoint was encountered by
-printing the line of code before which the program is halted.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{catch exception @var{name}}
-
-This command causes the program execution to stop whenever exception
-@code{name} is raised.  If @code{name} is omitted, then the execution is
-suspended when any exception is raised.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{print @var{expression}}
-
-This will print the value of the given expression. Most simple
-Ada expression formats are properly handled by @code{GDB}, so the expression
-can contain function calls, variables, operators, and attribute references.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{continue}
-
-Continues execution following a breakpoint, until the next breakpoint or the
-termination of the program.
-@end table
-
-@item 
-
-@table @asis
-
-@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)
-the called subprogram.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{next}
-
-Executes a single line. If this line is a subprogram call, executes and
-returns from the call.
-@end table
-
-@item 
-
-@table @asis
-
-@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
-relevant source file displayed. Successive applications of this command
-print subsequent lines. The command can be given an argument which is a
-line number, in which case it displays a few lines around the specified one.
-@end table
-
-@item 
-
-@table @asis
-
-@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
-leads to the current breakpoint. The display includes one line for each
-activation record (frame) corresponding to an active subprogram.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{up}
-
-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
-
-@item 
-
-@table @asis
-
-@item @code{down}
-
-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
-
-@item 
-
-@table @asis
-
-@item @code{frame @var{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.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{kill}
-
-Kills the child process in which the program is running under GDB.
-This may be useful for several purposes:
-
-
-@itemize *
-
-@item 
-It allows you to recompile and relink your program, since on many systems
-you cannot regenerate an executable file while it is running in a process.
-
-@item 
-You can run your program outside the debugger, on systems that do not
-permit executing a program outside GDB while breakpoints are set
-within GDB.
-
-@item 
-It allows you to debug a core dump rather than a running process.
-@end itemize
-@end table
-@end itemize
-
-The above list is a very short introduction to the commands that
-@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}.
-Note that most commands can be abbreviated
-(for example, c for continue, bt for backtrace).
-
-@node Using Ada Expressions,Calling User-Defined Subprograms,Introduction to GDB Commands,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id6}@anchor{154}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{155}
-@subsection Using Ada Expressions
-
-
-@geindex Ada expressions (in gdb)
-
-@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 @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 @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 @code{GDB} user.
-@end itemize
-@end quotation
-
-Thus, for brevity, the debugger acts as if there were
-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,
-@code{GDB} asks the user’s intent.
-
-For details on the supported Ada syntax, see @cite{Debugging with GDB}.
-
-@node Calling User-Defined Subprograms,Using the next Command in a Function,Using Ada Expressions,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution calling-user-defined-subprograms}@anchor{156}@anchor{gnat_ugn/gnat_and_program_execution id7}@anchor{157}
-@subsection Calling User-Defined Subprograms
-
-
-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:
-
-@quotation
-
-@example
-call subprogram-name (parameters)
-@end example
-@end quotation
-
-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 @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).
-
-The most important use of this facility is in allowing the inclusion of
-debugging routines that are tailored to particular data structures
-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
-@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.
-
-For example, when debugging GNAT itself, it is crucial to have access to
-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 @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
-syntactic category of the node, its position in the source, the integers
-that denote descendant nodes and parent node, as well as varied
-semantic information. To study this example in more detail, you might want to
-look at the body of the PN procedure in the stated file.
-
-Another useful application of this capability is to deal with situations of
-complex data which are not handled suitably by GDB. For example, if you specify
-Convention Fortran for a multi-dimensional array, GDB does not know that
-the ordering of array elements has been switched and will not properly
-address the array elements. In such a case, instead of trying to print the
-elements directly from GDB, you can write a callable procedure that prints
-the elements in the desired format.
-
-@node Using the next Command in a Function,Stopping When Ada Exceptions Are Raised,Calling User-Defined Subprograms,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id8}@anchor{158}@anchor{gnat_ugn/gnat_and_program_execution using-the-next-command-in-a-function}@anchor{159}
-@subsection Using the `next' Command in a Function
-
-
-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 @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
-this epilogue code, and it is typically associated with the last return
-statement in the function if there is more than one return. In some
-implementations, this epilogue is associated with the first statement
-of the function.
-
-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.
-The value returned is always that from the first return statement
-that was stepped through.
-
-@node Stopping When Ada Exceptions Are Raised,Ada Tasks,Using the next Command in a Function,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id9}@anchor{15a}@anchor{gnat_ugn/gnat_and_program_execution stopping-when-ada-exceptions-are-raised}@anchor{15b}
-@subsection Stopping When Ada Exceptions Are Raised
-
-
-@geindex Exceptions (in gdb)
-
-You can set catchpoints that stop the program execution when your program
-raises selected exceptions.
-
-
-@itemize *
-
-@item 
-
-@table @asis
-
-@item @code{catch exception}
-
-Set a catchpoint that stops execution whenever (any task in the) program
-raises any exception.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{catch exception @var{name}}
-
-Set a catchpoint that stops execution whenever (any task in the) program
-raises the exception `name'.
-@end table
-
-@item 
-
-@table @asis
-
-@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.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{info exceptions}, @code{info exceptions @var{regexp}}
-
-The @code{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'.
-@end table
-@end itemize
-
-@geindex Tasks (in gdb)
-
-@node Ada Tasks,Debugging Generic Units,Stopping When Ada Exceptions Are Raised,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution ada-tasks}@anchor{15c}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{15d}
-@subsection Ada Tasks
-
-
-@code{GDB} allows the following task-related commands:
-
-
-@itemize *
-
-@item 
-
-@table @asis
-
-@item @code{info tasks}
-
-This command shows a list of current Ada tasks, as in the following example:
-
-@example
-(gdb) info tasks
-  ID       TID P-ID   Thread Pri State                 Name
-   1   8088000   0   807e000  15 Child Activation Wait main_task
-   2   80a4000   1   80ae000  15 Accept/Select Wait    b
-   3   809a800   1   80a4800  15 Child Activation Wait a
-*  4   80ae800   3   80b8000  15 Running               c
-@end example
-
-In this listing, the asterisk before the first task indicates it to be the
-currently running task. The first column lists the task ID that is used
-to refer to tasks in the following commands.
-@end table
-@end itemize
-
-@geindex Breakpoints and tasks
-
-
-@itemize *
-
-@item 
-@code{break} `linespec' @code{task} `taskid', @code{break} `linespec' @code{task} `taskid' @code{if} …
-
-@quotation
-
-These commands are like the @code{break ... thread ...}.
-`linespec' specifies source lines.
-
-Use the qualifier @code{task @var{taskid}} with a breakpoint command
-to specify that you only want @code{GDB} to stop the program when a
-particular Ada task reaches this breakpoint. `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 @var{taskid}} when you set a
-breakpoint, the breakpoint applies to `all' tasks of your
-program.
-
-You can use the @code{task} qualifier on conditional breakpoints as
-well; in this case, place @code{task @var{taskid}} before the
-breakpoint condition (before the @code{if}).
-@end quotation
-@end itemize
-
-@geindex Task switching (in gdb)
-
-
-@itemize *
-
-@item 
-@code{task @var{taskno}}
-
-@quotation
-
-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
-perturbed.
-@end quotation
-@end itemize
-
-For more detailed information on the tasking support,
-see @cite{Debugging with GDB}.
-
-@geindex Debugging Generic Units
-
-@geindex Generics
-
-@node Debugging Generic Units,Remote Debugging with gdbserver,Ada Tasks,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution debugging-generic-units}@anchor{15e}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{15f}
-@subsection Debugging Generic Units
-
-
-GNAT always uses code expansion for generic instantiation. This means that
-each time an instantiation occurs, a complete copy of the original code is
-made, with appropriate substitutions of formals by actuals.
-
-It is not possible to refer to the original generic entities in
-@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
-
-@example
-procedure g is
-
-   generic package k is
-      procedure kp (v1 : in out integer);
-   end k;
-
-   package body k is
-      procedure kp (v1 : in out integer) is
-      begin
-         v1 := v1 + 1;
-      end kp;
-   end k;
-
-   package k1 is new k;
-   package k2 is new k;
-
-   var : integer := 1;
-
-begin
-   k1.kp (var);
-   k2.kp (var);
-   k1.kp (var);
-   k2.kp (var);
-end;
-@end example
-@end quotation
-
-Then to break on a call to procedure kp in the k2 instance, simply
-use the command:
-
-@quotation
-
-@example
-(gdb) break g.k2.kp
-@end example
-@end quotation
-
-When the breakpoint occurs, you can step through the code of the
-instance in the normal manner and examine the values of local variables, as for
-other units.
-
-@geindex Remote Debugging with gdbserver
-
-@node Remote Debugging with gdbserver,GNAT Abnormal Termination or Failure to Terminate,Debugging Generic Units,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id12}@anchor{160}@anchor{gnat_ugn/gnat_and_program_execution remote-debugging-with-gdbserver}@anchor{161}
-@subsection Remote Debugging with gdbserver
-
-
-On platforms where gdbserver is supported, it is possible to use this tool
-to debug your application remotely.  This can be useful in situations
-where the program needs to be run on a target host that is different
-from the host used for development, particularly when the target has
-a limited amount of resources (either CPU and/or memory).
-
-To do so, start your program using gdbserver on the target machine.
-gdbserver then automatically suspends the execution of your program
-at its entry point, waiting for a debugger to connect to it.  The
-following commands starts an application and tells gdbserver to
-wait for a connection with the debugger on localhost port 4444.
-
-@quotation
-
-@example
-$ gdbserver localhost:4444 program
-Process program created; pid = 5685
-Listening on port 4444
-@end example
-@end quotation
-
-Once gdbserver has started listening, we can tell the debugger to establish
-a connection with this gdbserver, and then start the same debugging session
-as if the program was being debugged on the same host, directly under
-the control of GDB.
-
-@quotation
-
-@example
-$ gdb program
-(gdb) target remote targethost:4444
-Remote debugging using targethost:4444
-0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so.
-(gdb) b foo.adb:3
-Breakpoint 1 at 0x401f0c: file foo.adb, line 3.
-(gdb) continue
-Continuing.
-
-Breakpoint 1, foo () at foo.adb:4
-4       end foo;
-@end example
-@end quotation
-
-It is also possible to use gdbserver to attach to an already running
-program, in which case the execution of that program is simply suspended
-until the connection between the debugger and gdbserver is established.
-
-For more information on how to use gdbserver, see the `Using the gdbserver Program'
-section in @cite{Debugging with GDB}.
-GNAT provides support for gdbserver on x86-linux, x86-windows and x86_64-linux.
-
-@geindex Abnormal Termination or Failure to Terminate
-
-@node GNAT Abnormal Termination or Failure to Terminate,Naming Conventions for GNAT Source Files,Remote Debugging with gdbserver,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution gnat-abnormal-termination-or-failure-to-terminate}@anchor{162}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{163}
-@subsection GNAT Abnormal Termination or Failure to Terminate
-
-
-When presented with programs that contain serious errors in syntax
-or semantics,
-GNAT may on rare occasions  experience problems in operation, such
-as aborting with a
-segmentation fault or illegal memory access, raising an internal
-exception, terminating abnormally, or failing to terminate at all.
-In such cases, you can activate
-various features of GNAT that can help you pinpoint the construct in your
-program that is the likely source of the problem.
-
-The following strategies are presented in increasing order of
-difficulty, corresponding to your experience in using GNAT and your
-familiarity with compiler internals.
-
-
-@itemize *
-
-@item 
-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 @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 @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.
-@end itemize
-
-@geindex -gnatdc switch
-
-
-@itemize *
-
-@item 
-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
-@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 @code{gcc}). You can use @code{gdb} on @code{gnat1} as you
-would on a C program (but @ref{14f,,The GNAT Debugger GDB} for caveats). The
-@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
-
-@node Naming Conventions for GNAT Source Files,Getting Internal Debugging Information,GNAT Abnormal Termination or Failure to Terminate,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id14}@anchor{164}@anchor{gnat_ugn/gnat_and_program_execution naming-conventions-for-gnat-source-files}@anchor{165}
-@subsection Naming Conventions for GNAT Source Files
-
-
-In order to examine the workings of the GNAT system, the following
-brief description of its organization may be helpful:
-
-
-@itemize *
-
-@item 
-Files with prefix @code{sc} contain the lexical scanner.
-
-@item 
-All files prefixed with @code{par} are components of the parser. The
-numbers correspond to chapters of the Ada Reference Manual. For example,
-parsing of select statements can be found in @code{par-ch9.adb}.
-
-@item 
-All files prefixed with @code{sem} perform semantic analysis. The
-numbers correspond to chapters of the Ada standard. For example, all
-issues involving context clauses can be found in @code{sem_ch10.adb}. In
-addition, some features of the language require sufficient special processing
-to justify their own semantic files: sem_aggr for aggregates, sem_disp for
-dynamic dispatching, etc.
-
-@item 
-All files prefixed with @code{exp} perform normalization and
-expansion of the intermediate representation (abstract syntax tree, or AST).
-these files use the same numbering scheme as the parser and semantics files.
-For example, the construction of record initialization procedures is done in
-@code{exp_ch3.adb}.
-
-@item 
-The files prefixed with @code{bind} implement the binder, which
-verifies the consistency of the compilation, determines an order of
-elaboration, and generates the bind file.
-
-@item 
-The files @code{atree.ads} and @code{atree.adb} detail the low-level
-data structures used by the front-end.
-
-@item 
-The files @code{sinfo.ads} and @code{sinfo.adb} detail the structure of
-the abstract syntax tree as produced by the parser.
-
-@item 
-The files @code{einfo.ads} and @code{einfo.adb} detail the attributes of
-all entities, computed during semantic analysis.
-
-@item 
-Library management issues are dealt with in files with prefix
-@code{lib}.
-
-@geindex Annex A (in Ada Reference Manual)
-
-@item 
-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 @code{Interfaces}, as
-defined in Annex B.
-
-@geindex System (package in Ada Reference Manual)
-
-@item 
-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 @code{GNAT}. These are useful
-general-purpose packages, fully documented in their specs. All
-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
-@anchor{gnat_ugn/gnat_and_program_execution getting-internal-debugging-information}@anchor{166}@anchor{gnat_ugn/gnat_and_program_execution id15}@anchor{167}
-@subsection Getting Internal Debugging Information
-
-
-Most compilers have internal debugging switches and modes. GNAT
-does also, except GNAT internal debugging switches and modes are not
-secret. A summary and full description of all the compiler and binder
-debug flags are in the file @code{debug.adb}. You must obtain the
-sources of the compiler to see the full detailed effects of these flags.
-
-The switches that print the source of the program (reconstructed from
-the internal tree) are of general interest for user programs, as are the
-options to print
-the full internal tree, and the entity table (the symbol table
-information). The reconstructed source provides a readable version of the
-program after the front-end has completed analysis and  expansion,
-and is useful when studying the performance of specific constructs.
-For example, constraint checks are indicated, complex aggregates
-are replaced with loops and assignments, and tasking primitives
-are replaced with run-time calls.
-
-@geindex traceback
-
-@geindex stack traceback
-
-@geindex stack unwinding
-
-@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 id16}@anchor{168}@anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{169}
-@subsection Stack Traceback
-
-
-Traceback is a mechanism to display the sequence of subprogram calls that
-leads to a specified execution point in a program. Often (but not always)
-the execution point is an instruction at which an exception has been raised.
-This mechanism is also known as `stack unwinding' because it obtains
-its information by scanning the run-time stack and recovering the activation
-records of all active subprograms. Stack unwinding is one of the most
-important tools for program debugging.
-
-The first entry stored in traceback corresponds to the deepest calling level,
-that is to say the subprogram currently executing the instruction
-from which we want to obtain the traceback.
-
-Note that there is no runtime performance penalty when stack traceback
-is enabled, and no exception is raised during program execution.
-
-@geindex traceback
-@geindex non-symbolic
-
-@menu
-* Non-Symbolic Traceback:: 
-* Symbolic Traceback:: 
-
-@end menu
-
-@node Non-Symbolic Traceback,Symbolic Traceback,,Stack Traceback
-@anchor{gnat_ugn/gnat_and_program_execution id17}@anchor{16a}@anchor{gnat_ugn/gnat_and_program_execution non-symbolic-traceback}@anchor{16b}
-@subsubsection Non-Symbolic Traceback
-
-
-Note: this feature is not supported on all platforms. See
-@code{GNAT.Traceback} spec in @code{g-traceb.ads}
-for a complete list of supported platforms.
-
-@subsubheading 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 @code{-E} @code{gnatbind} option. With
-this option a stack traceback is stored as part of exception information.
-
-You can translate this information using the @code{addr2line} tool, provided that
-the program is compiled with debugging options (see @ref{db,,Compiler Switches})
-and linked at a fixed position with @code{-no-pie}.
-
-Here is a simple example with @code{gnatmake}:
-
-@quotation
-
-@example
-procedure STB is
-
-   procedure P1 is
-   begin
-      raise Constraint_Error;
-   end P1;
-
-   procedure P2 is
-   begin
-      P1;
-   end P2;
-
-begin
-   P2;
-end STB;
-@end example
-
-@example
-$ gnatmake stb -g -bargs -E -largs -no-pie
-$ stb
-
-Execution of stb terminated by unhandled exception
-raised CONSTRAINT_ERROR : stb.adb:5 explicit raise
-Load address: 0x400000
-Call stack traceback locations:
-0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
-@end example
-@end quotation
-
-As we see the traceback lists a sequence of addresses for the unhandled
-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 @code{addr2line}
-tool needs to be invoked like this:
-
-@quotation
-
-@example
-$ addr2line -e stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4
-   0x4011f1 0x77e892a4
-
-d:/stb/stb.adb:5
-d:/stb/stb.adb:10
-d:/stb/stb.adb:14
-d:/stb/b~stb.adb:197
-crtexe.c:?
-crtexe.c:?
-??:0
-@end example
-@end quotation
-
-The @code{addr2line} tool has several other useful options:
-
-@quotation
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@item
-
-@code{-a --addresses}
-
-@tab
-
-to show the addresses alongside the line numbers
-
-@item
-
-@code{-f --functions}
-
-@tab
-
-to get the function name corresponding to a location
-
-@item
-
-@code{-p --pretty-print}
-
-@tab
-
-to print all the information on a single line
-
-@item
-
-@code{--demangle=gnat}
-
-@tab
-
-to use the GNAT decoding mode for the function names
-
-@end multitable
-
-
-@example
-$ addr2line -e stb -a -f -p --demangle=gnat 0x401373 0x40138b
-   0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
-
-0x00401373: stb.p1 at d:/stb/stb.adb:5
-0x0040138B: stb.p2 at d:/stb/stb.adb:10
-0x0040139C: stb at d:/stb/stb.adb:14
-0x00401335: main at d:/stb/b~stb.adb:197
-0x004011c4: ?? at crtexe.c:?
-0x004011f1: ?? at crtexe.c:?
-0x77e892a4: ?? ??:0
-@end example
-@end quotation
-
-From this traceback we can see that the exception was raised in @code{stb.adb}
-at line 5, which was reached from a procedure call in @code{stb.adb} at line
-10, and so on. The @code{b~std.adb} is the binder file, which contains the
-call to the main program. @ref{10e,,Running gnatbind}. The remaining entries are
-assorted runtime routines and the output will vary from platform to platform.
-
-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:
-
-@example
-$ gdb -nw stb
-
-(gdb) break *0x401373
-Breakpoint 1 at 0x401373: file stb.adb, line 5.
-@end example
-
-It is important to note that the stack traceback addresses do not change when
-debug information is included. This is particularly useful because it makes it
-possible to release software without debug information (to minimize object
-size), get a field report that includes a stack traceback whenever an internal
-bug occurs, and then be able to retrieve the sequence of calls with the same
-program compiled with debug information.
-
-However the @code{addr2line} tool does not work with Position-Independent Code
-(PIC), the historical example being Windows DLLs, which nowadays encompasses
-Position-Independent Executables (PIE) on recent Windows versions.
-
-In order to translate addresses into the source lines with Position-Independent
-Executables on recent Windows versions, in other words without using the switch
-@code{-no-pie} during linking, you need to use the @code{gnatsymbolize} tool
-with @code{--load} instead of the @code{addr2line} tool. The main difference
-is that you need to copy the Load Address output in the traceback ahead of the
-sequence of addresses. And the default mode of @code{gnatsymbolize} is equivalent
-to that of @code{addr2line} with the above switches, so none of them is needed:
-
-@example
-$ gnatmake stb -g -bargs -E
-$ stb
-
-Execution of stb terminated by unhandled exception
-raised CONSTRAINT_ERROR : stb.adb:5 explicit raise
-Load address: 0x400000
-Call stack traceback locations:
-0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
-
-$ gnatsymbolize --load stb 0x400000 0x401373 0x40138b 0x40139c 0x401335
-   0x4011c4 0x4011f1 0x77e892a4
-
-0x00401373 Stb.P1 at stb.adb:5
-0x0040138B Stb.P2 at stb.adb:10
-0x0040139C Stb at stb.adb:14
-0x00401335 Main at b~stb.adb:197
-0x004011c4 __tmainCRTStartup at ???
-0x004011f1 mainCRTStartup at ???
-0x77e892a4 ??? at ???
-@end example
-
-@subsubheading Tracebacks From Exception Occurrences
-
-
-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 @code{Ada.Exceptions}. Here is a simple example:
-
-@quotation
-
-@example
-with Ada.Text_IO;
-with Ada.Exceptions;
-
-procedure STB is
-
-   use Ada;
-   use Ada.Exceptions;
-
-   procedure P1 is
-      K : Positive := 1;
-   begin
-      K := K - 1;
-   exception
-      when E : others =>
-         Text_IO.Put_Line (Exception_Information (E));
-   end P1;
-
-   procedure P2 is
-   begin
-      P1;
-   end P2;
-
-begin
-   P2;
-end STB;
-@end example
-@end quotation
-
-This program will output:
-
-@quotation
-
-@example
-$ stb
-
-raised CONSTRAINT_ERROR : stb.adb:12 range check failed
-Load address: 0x400000
-Call stack traceback locations:
-0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4
-@end example
-@end quotation
-
-@subsubheading Tracebacks From Anywhere in a Program
-
-
-It is also possible to retrieve a stack traceback from anywhere in a program.
-For this you need to 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 @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 @code{GNAT.Debug_Utilities.Image} to convert
-addresses to strings:
-
-@quotation
-
-@example
-with Ada.Text_IO;
-with GNAT.Traceback;
-with GNAT.Debug_Utilities;
-
-procedure STB is
-
-   use Ada;
-   use GNAT;
-   use GNAT.Traceback;
-
-   procedure P1 is
-      TB  : Tracebacks_Array (1 .. 10);
-      --  We are asking for a maximum of 10 stack frames.
-      Len : Natural;
-      --  Len will receive the actual number of stack frames returned.
-   begin
-      Call_Chain (TB, Len);
-
-      Text_IO.Put ("In STB.P1 : ");
-
-      for K in 1 .. Len loop
-         Text_IO.Put (Debug_Utilities.Image (TB (K)));
-         Text_IO.Put (' ');
-      end loop;
-
-      Text_IO.New_Line;
-   end P1;
-
-   procedure P2 is
-   begin
-      P1;
-   end P2;
-
-begin
-   P2;
-end STB;
-@end example
-
-@example
-$ gnatmake stb -g
-$ stb
-
-In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C#
-16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4#
-@end example
-@end quotation
-
-You can then get further information by invoking the @code{addr2line} tool or
-the @code{gnatsymbolize} tool as described earlier (note that the hexadecimal
-addresses need to be specified in C format, with a leading ‘0x’).
-
-@geindex traceback
-@geindex symbolic
-
-@node Symbolic Traceback,,Non-Symbolic Traceback,Stack Traceback
-@anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{16c}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{16d}
-@subsubsection Symbolic Traceback
-
-
-A symbolic traceback is a stack traceback in which procedure names are
-associated with each code location.
-
-Note that this feature is not supported on all platforms. See
-@code{GNAT.Traceback.Symbolic} spec in @code{g-trasym.ads} for a complete
-list of currently supported platforms.
-
-Note that the symbolic traceback requires that the program be compiled
-with debug information. If it is not compiled with debug information
-only the non-symbolic information will be valid.
-
-@subsubheading Tracebacks From Exception Occurrences
-
-
-Here is an example:
-
-@quotation
-
-@example
-with Ada.Text_IO;
-with GNAT.Traceback.Symbolic;
-
-procedure STB is
-
-   procedure P1 is
-   begin
-      raise Constraint_Error;
-   end P1;
-
-   procedure P2 is
-   begin
-      P1;
-   end P2;
-
-   procedure P3 is
-   begin
-      P2;
-   end P3;
-
-begin
-   P3;
-exception
-   when E : others =>
-      Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E));
-end STB;
-@end example
-
-@example
-$ gnatmake -g .\stb -bargs -E
-$ stb
-
-0040149F in stb.p1 at stb.adb:8
-004014B7 in stb.p2 at stb.adb:13
-004014CF in stb.p3 at stb.adb:18
-004015DD in ada.stb at stb.adb:22
-00401461 in main at b~stb.adb:168
-004011C4 in __mingw_CRTStartup at crt1.c:200
-004011F1 in mainCRTStartup at crt1.c:222
-77E892A4 in ?? at ??:0
-@end example
-@end quotation
-
-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 @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 @code{Symbolic_Traceback} to compute the symbolic
-information. Here is an example:
-
-@quotation
-
-@example
-with Ada.Text_IO;
-with GNAT.Traceback;
-with GNAT.Traceback.Symbolic;
-
-procedure STB is
-
-   use Ada;
-   use GNAT.Traceback;
-   use GNAT.Traceback.Symbolic;
-
-   procedure P1 is
-      TB  : Tracebacks_Array (1 .. 10);
-      --  We are asking for a maximum of 10 stack frames.
-      Len : Natural;
-      --  Len will receive the actual number of stack frames returned.
-   begin
-      Call_Chain (TB, Len);
-      Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len)));
-   end P1;
-
-   procedure P2 is
-   begin
-      P1;
-   end P2;
-
-begin
-   P2;
-end STB;
-@end example
-@end quotation
-
-@subsubheading Automatic Symbolic Tracebacks
-
-
-Symbolic tracebacks may also be enabled by using the -Es switch to gnatbind (as
-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{16e}@anchor{gnat_ugn/gnat_and_program_execution pretty-printers-for-the-gnat-runtime}@anchor{16f}
-@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 Profiling
-
-@node Profiling,Improving Performance,Running and Debugging Ada Programs,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{170}@anchor{gnat_ugn/gnat_and_program_execution profiling}@anchor{147}
-@section Profiling
-
-
-This section describes how to use the @code{gprof} profiler tool on Ada programs.
-
-@geindex gprof
-
-@geindex Profiling
-
-@menu
-* Profiling an Ada Program with gprof:: 
-
-@end menu
-
-@node Profiling an Ada Program with gprof,,,Profiling
-@anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{171}@anchor{gnat_ugn/gnat_and_program_execution profiling-an-ada-program-with-gprof}@anchor{172}
-@subsection Profiling an Ada Program with 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.
-
-@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
-
-
-@itemize *
-
-@item 
-Linux x86/x86_64
-
-@item 
-Windows x86/x86_64 (without PIE support)
-@end itemize
-
-In order to profile a program using @code{gprof}, several steps are needed:
-
-
-@enumerate 
-
-@item 
-Instrument the code, which requires a full recompilation of the project with the
-proper switches.
-
-@item 
-Execute the program under the analysis conditions, i.e. with the desired
-input.
-
-@item 
-Analyze the results using the @code{gprof} tool.
-@end enumerate
-
-The following sections detail the different steps, and indicate how
-to interpret the results.
-
-@menu
-* Compilation for profiling:: 
-* Program execution:: 
-* Running gprof:: 
-* Interpretation of profiling results:: 
-
-@end menu
-
-@node Compilation for profiling,Program execution,,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{173}@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{174}
-@subsubsection Compilation for profiling
-
-
-@geindex -pg (gcc)
-@geindex for profiling
-
-@geindex -pg (gnatlink)
-@geindex for profiling
-
-In order to profile a program the first step is to tell the compiler
-to generate the necessary profiling information. The compiler switch to be used
-is @code{-pg}, which must be added to other compilation switches. This
-switch needs to be specified both during compilation and link stages, and can
-be specified once when using gnatmake:
-
-@quotation
-
-@example
-$ gnatmake -f -pg -P my_project
-@end example
-@end quotation
-
-Note that only the objects that were compiled with the @code{-pg} switch will
-be profiled; if you need to profile your whole project, use the @code{-f}
-gnatmake switch to force full recompilation.
-
-Note that on Windows, gprof does not support PIE. The @code{-no-pie} switch
-should be added to the linker flags to disable this feature.
-
-@node Program execution,Running gprof,Compilation for profiling,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{175}@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{176}
-@subsubsection Program execution
-
-
-Once the program has been compiled for profiling, you can run it as usual.
-
-The only constraint imposed by profiling is that the program must terminate
-normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be
-properly analyzed.
-
-Once the program completes execution, a data file called @code{gmon.out} is
-generated in the directory where the program was launched from. If this file
-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 id24}@anchor{177}@anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{178}
-@subsubsection Running gprof
-
-
-The @code{gprof} tool is called as follow:
-
-@quotation
-
-@example
-$ gprof my_prog gmon.out
-@end example
-@end quotation
-
-or simply:
-
-@quotation
-
-@example
-$ gprof my_prog
-@end example
-@end quotation
-
-The complete form of the gprof command line is the following:
-
-@quotation
-
-@example
-$ gprof [switches] [executable [data-file]]
-@end example
-@end quotation
-
-@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.
-
-The following is the subset of those switches that is most relevant:
-
-@geindex --demangle (gprof)
-
-
-@table @asis
-
-@item @code{--demangle[=@var{style}]}, @code{--no-demangle}
-
-These options control whether symbol names should be demangled when
-printing output.  The default is to demangle C++ symbols.  The
-@code{--no-demangle} option may be used to turn off demangling. Different
-compilers have different mangling styles.  The optional demangling style
-argument can be used to choose an appropriate demangling style for your
-compiler, in particular Ada symbols generated by GNAT can be demangled using
-@code{--demangle=gnat}.
-@end table
-
-@geindex -e (gprof)
-
-
-@table @asis
-
-@item @code{-e @var{function_name}}
-
-The @code{-e @var{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 @code{function_name} may be indicated with each @code{-e}
-option.
-@end table
-
-@geindex -E (gprof)
-
-
-@table @asis
-
-@item @code{-E @var{function_name}}
-
-The @code{-E @var{function}} option works like the @code{-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 @code{-E} option may be given; only one
-@code{function_name} may be indicated with each @code{-E`} option.
-@end table
-
-@geindex -f (gprof)
-
-
-@table @asis
-
-@item @code{-f @var{function_name}}
-
-The @code{-f @var{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 @code{function_name} may be indicated with each @code{-f}
-option.
-@end table
-
-@geindex -F (gprof)
-
-
-@table @asis
-
-@item @code{-F @var{function_name}}
-
-The @code{-F @var{function}} option works like the @code{-f} option, but
-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 @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 id25}@anchor{179}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{17a}
-@subsubsection Interpretation of profiling results
-
-
-The results of the profiling analysis are represented by two arrays: the
-‘flat profile’ and the ‘call graph’. Full documentation of those outputs
-can be found in the GNU Profiler User’s Guide.
-
-The flat profile shows the time spent in each function of the program, and how
-many time it has been called. This allows you to locate easily the most
-time-consuming functions.
-
-The call graph shows, for each subprogram, the subprograms that call it,
-and the subprograms that it calls. It also provides an estimate of the time
-spent in each of those callers/called subprograms.
-
-@node Improving Performance,Overflow Check Handling in GNAT,Profiling,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{148}@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{17b}
-@section Improving Performance
-
-
-@geindex Improving performance
-
-This section presents several topics related to program performance.
-It first describes some of the tradeoffs that need to be considered
-and some of the techniques for making your program run faster.
-
-It then documents the unused subprogram/data elimination feature,
-which can reduce the size of program executables.
-
-@menu
-* Performance Considerations:: 
-* Text_IO Suggestions:: 
-* Reducing Size of Executables with Unused Subprogram/Data Elimination:: 
-
-@end menu
-
-@node Performance Considerations,Text_IO Suggestions,,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{17c}@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{17d}
-@subsection Performance Considerations
-
-
-The GNAT system provides a number of options that allow a trade-off
-between
-
-
-@itemize *
-
-@item 
-performance of the generated code
-
-@item 
-speed of compilation
-
-@item 
-minimization of dependences and recompilation
-
-@item 
-the degree of run-time checking.
-@end itemize
-
-The defaults (if no options are selected) aim at improving the speed
-of compilation and minimizing dependences, at the expense of performance
-of the generated code:
-
-
-@itemize *
-
-@item 
-no optimization
-
-@item 
-no inlining of subprogram calls
-
-@item 
-all run-time checks enabled except overflow and elaboration checks
-@end itemize
-
-These options are suitable for most program development purposes. This
-section describes how you can modify these choices, and also provides
-some guidelines on debugging optimized code.
-
-@menu
-* Controlling Run-Time Checks:: 
-* Use of Restrictions:: 
-* Optimization Levels:: 
-* Debugging Optimized Code:: 
-* Inlining of Subprograms:: 
-* Floating Point Operations:: 
-* Vectorization of loops:: 
-* Other Optimization Switches:: 
-* Optimization and Strict Aliasing:: 
-* Aliased Variables and Optimization:: 
-* Atomic Variables and Optimization:: 
-* Passive Task Optimization:: 
-
-@end menu
-
-@node Controlling Run-Time Checks,Use of Restrictions,,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{17e}@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{17f}
-@subsubsection Controlling Run-Time Checks
-
-
-By default, GNAT generates all run-time checks, except stack overflow
-checks, and checks for access before elaboration on subprogram
-calls. The latter are not required in default mode, because all
-necessary checking is done at compile time.
-
-@geindex -gnatp (gcc)
-
-@geindex -gnato (gcc)
-
-The gnat switch, @code{-gnatp} allows this default to be modified. See
-@ref{ea,,Run-Time Checks}.
-
-Our experience is that the default is suitable for most development
-purposes.
-
-Elaboration checks are off by default, and also not needed by default, since
-GNAT uses a static elaboration analysis approach that avoids the need for
-run-time checking. This manual contains a full chapter discussing the issue
-of elaboration checks, and if the default is not satisfactory for your use,
-you should read this chapter.
-
-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 @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 @code{-gnatVn}. Validity checks
-are also suppressed entirely if @code{-gnatp} is used.
-
-@geindex Overflow checks
-
-@geindex Checks
-@geindex overflow
-
-@geindex Suppress
-
-@geindex Unsuppress
-
-@geindex pragma Suppress
-
-@geindex pragma Unsuppress
-
-Note that the setting of the switches controls the default setting of
-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 id29}@anchor{180}@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{181}
-@subsubsection Use of Restrictions
-
-
-The use of pragma Restrictions allows you to control which features are
-permitted in your program. Apart from the obvious point that if you avoid
-relatively expensive features like finalization (enforceable by the use
-of pragma Restrictions (No_Finalization)), the use of this pragma does not
-affect the generated code in most cases.
-
-One notable exception to this rule is that the possibility of task abort
-results in some distributed overhead, particularly if finalization or
-exception handlers are used. The reason is that certain sections of code
-have to be marked as non-abortable.
-
-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.
-The relevant restrictions pragmas are
-
-@quotation
-
-@example
-pragma Restrictions (No_Abort_Statements);
-pragma Restrictions (Max_Asynchronous_Select_Nesting => 0);
-@end example
-@end quotation
-
-It is recommended that these restriction pragmas be used if possible. Note
-that this also means that you can write code without worrying about the
-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 id30}@anchor{182}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{ed}
-@subsubsection Optimization Levels
-
-
-@geindex -O (gcc)
-
-Without any optimization option,
-the compiler’s goal is to reduce the cost of
-compilation and to make debugging produce the expected results.
-Statements are independent: if you stop the program with a breakpoint between
-statements, you can then assign a new value to any variable or change
-the program counter to any other statement in the subprogram and get exactly
-the results you would expect from the source code.
-
-Turning on optimization makes the compiler attempt to improve the
-performance and/or code size at the expense of compilation time and
-possibly the ability to debug the program.
-
-If you use multiple
--O options, with or without level numbers,
-the last such option is the one that is effective.
-
-The default is optimization off. This results in the fastest compile
-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
-@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 *
-
-@item 
-
-@table @asis
-
-@item @code{-O0}
-
-No optimization (the default);
-generates unoptimized code but has
-the fastest compilation time.
-
-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 @code{-O1}
-
-Moderate optimization;
-optimizes reasonably well but does not
-degrade compilation time significantly.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{-O2}
-
-Full optimization;
-generates highly optimized code and has
-the slowest compilation time.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{-O3}
-
-Full optimization as in @code{-O2};
-also uses more aggressive automatic inlining of subprograms within a unit
-(@ref{100,,Inlining of Subprograms}) and attempts to vectorize loops.
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{-Os}
-
-Optimize space usage (code and data) of resulting program.
-@end table
-@end itemize
-
-Higher optimization levels perform more global transformations on the
-program and apply more expensive analysis algorithms in order to generate
-faster and more compact code. The price in compilation time, and the
-resulting improvement in execution time,
-both depend on the particular application and the hardware environment.
-You should experiment to find the best level for your application.
-
-Since the precise set of optimizations done at each level will vary from
-release to release (and sometime from target to target), it is best to think
-of the optimization settings in general terms.
-See the `Options That Control Optimization' section in
-@cite{Using the GNU Compiler Collection (GCC)}
-for details about
-the @code{-O} settings and a number of @code{-f} options that
-individually enable or disable specific optimizations.
-
-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 `unoptimized' code. Selecting a lower
-level of optimization does not improve the reliability of the code
-generator, which in practice is highly reliable at all optimization
-levels.
-
-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{100,,Inlining of Subprograms}.
-
-@node Debugging Optimized Code,Inlining of Subprograms,Optimization Levels,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{183}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{184}
-@subsubsection Debugging Optimized Code
-
-
-@geindex Debugging optimized code
-
-@geindex Optimization and debugging
-
-Although it is possible to do a reasonable amount of debugging at
-nonzero optimization levels,
-the higher the level the more likely that
-source-level constructs will have been eliminated by optimization.
-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 @code{-O2} or @code{-O3}.
-Explicit temporary variables that you code might be eliminated at
-level @code{-O1} or higher.
-
-@geindex -g (gcc)
-
-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.
-However, it has no effect on the generated code (and thus does not
-degrade performance)
-
-Since the compiler generates debugging tables for a compilation unit before
-it performs optimizations, the optimizing transformations may invalidate some
-of the debugging data.  You therefore need to anticipate certain
-anomalous situations that may arise while debugging optimized code.
-These are the most common cases:
-
-
-@itemize *
-
-@item 
-`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:
-
-
-@itemize -
-
-@item 
-`Common subexpression elimination:' using a single instance of code for a
-quantity that the source computes several times.  As a result you
-may not be able to stop on what looks like a statement.
-
-@item 
-`Invariant code motion:' moving an expression that does not change within a
-loop, to the beginning of the loop.
-
-@item 
-`Instruction scheduling:' moving instructions so as to
-overlap loads and stores (typically) with other code, or in
-general to move computations of values closer to their uses. Often
-this causes you to pass an assignment statement without the assignment
-happening and then later bounce back to the statement when the
-value is actually needed.  Placing a breakpoint on a line of code
-and then stepping over it may, therefore, not always cause all the
-expected side-effects.
-@end itemize
-
-@item 
-`The ‘big leap’:' More commonly known as `cross-jumping', in which
-two identical pieces of code are merged and the program counter suddenly
-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 @code{goto}, a @code{return}, or
-a @code{break} in a C @code{switch} statement.
-
-@item 
-`The ‘roving variable’:' The symptom is an unexpected value in a variable.
-There are various reasons for this effect:
-
-
-@itemize -
-
-@item 
-In a subprogram prologue, a parameter may not yet have been moved to its
-‘home’.
-
-@item 
-A variable may be dead, and its register re-used.  This is
-probably the most common cause.
-
-@item 
-As mentioned above, the assignment of a value to a variable may
-have been moved.
-
-@item 
-A variable may be eliminated entirely by value propagation or
-other means.  In this case, GCC may incorrectly generate debugging
-information for the variable
-@end itemize
-
-In general, when an unexpected value appears for a local variable or parameter
-you should first ascertain if that value was actually computed by
-your program, as opposed to being incorrectly reported by the debugger.
-Record fields or
-array elements in an object designated by an access value
-are generally less of a problem, once you have ascertained that the access
-value is sensible.
-Typically, this means checking variables in the preceding code and in the
-calling subprogram to verify that the value observed is explainable from other
-values (one must apply the procedure recursively to those
-other values); or re-running the code and stopping a little earlier
-(perhaps before the call) and stepping to better see how the variable obtained
-the value in question; or continuing to step `from' the point of the
-strange value to see if code motion had simply moved the variable’s
-assignments later.
-@end itemize
-
-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 @code{-O1} and later @code{-O2} as
-the debugger becomes less critical.
-Whether to use the @code{-g} switch in the release version is
-a release management issue.
-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 id32}@anchor{185}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{100}
-@subsubsection Inlining of Subprograms
-
-
-A call to a subprogram in the current unit is inlined if all the
-following conditions are met:
-
-
-@itemize *
-
-@item 
-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 @code{gcc} cannot support in inlined
-subprograms.
-
-@geindex pragma Inline
-
-@geindex Inline
-
-@item 
-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 @code{-O2} is
-specified; optimization level @code{-O3} is specified.
-@end itemize
-
-Calls to subprograms in `with'ed 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:
-
-
-@itemize *
-
-@item 
-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 @code{gcc} cannot support in inlined
-subprograms.
-
-@item 
-There is a @code{pragma Inline} for the subprogram.
-
-@item 
-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
-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 @code{-gnatn} switch causes additional
-compilation dependencies. Consider the following:
-
-@quotation
-
-@example
-package R is
-   procedure Q;
-   pragma Inline (Q);
-end R;
-package body R is
-   ...
-end R;
-
-with R;
-procedure Main is
-begin
-   ...
-   R.Q;
-end Main;
-@end example
-@end quotation
-
-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 @code{R} does not require recompiling
-@code{Main}.
-
-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 @code{gcc}.
-
-The use of front end inlining with @code{-gnatN} generates similar
-additional dependencies.
-
-@geindex -fno-inline (gcc)
-
-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 @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 @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 @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 @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 @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 @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{186}@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{187}
-@subsubsection Floating Point Operations
-
-
-@geindex Floating-Point Operations
-
-On almost all targets, GNAT maps Float and Long_Float to the 32-bit and
-64-bit standard IEEE floating-point representations, and operations will
-use standard IEEE arithmetic as provided by the processor. On most, but
-not all, architectures, the attribute Machine_Overflows is False for these
-types, meaning that the semantics of overflow is implementation-defined.
-In the case of GNAT, these semantics correspond to the normal IEEE
-treatment of infinities and NaN (not a number) values. For example,
-1.0 / 0.0 yields plus infinitiy and 0.0 / 0.0 yields a NaN. By
-avoiding explicit overflow checks, the performance is greatly improved
-on many targets. However, if required, floating-point overflow can be
-enabled by the use of the pragma Check_Float_Overflow.
-
-Another consideration that applies specifically to x86 32-bit
-architectures is which form of floating-point arithmetic is used.
-By default the operations use the old style x86 floating-point,
-which implements an 80-bit extended precision form (on these
-architectures the type Long_Long_Float corresponds to that form).
-In addition, generation of efficient code in this mode means that
-the extended precision form will be used for intermediate results.
-This may be helpful in improving the final precision of a complex
-expression. However it means that the results obtained on the x86
-will be different from those on other architectures, and for some
-algorithms, the extra intermediate precision can be detrimental.
-
-In addition to this old-style floating-point, all modern x86 chips
-implement an alternative floating-point operation model referred
-to as SSE2. In this model there is no extended form, and furthermore
-execution performance is significantly enhanced. To force GNAT to use
-this more modern form, use both of the switches:
-
-@quotation
-
--msse2 -mfpmath=sse
-@end quotation
-
-A unit compiled with these switches will automatically use the more
-efficient SSE2 instruction set for Float and Long_Float operations.
-Note that the ABI has the same form for both floating-point models,
-so it is permissible to mix units compiled with and without these
-switches.
-
-@node Vectorization of loops,Other Optimization Switches,Floating Point Operations,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id34}@anchor{188}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{189}
-@subsubsection Vectorization of loops
-
-
-@geindex Optimization Switches
-
-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 @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 @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 @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 @code{-maltivec}.
-
-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
-@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
-
-@example
-A : array (1..4, 1..4) of Long_Float;
-S : array (1..4) of Long_Float;
-
-procedure Sum is
-begin
-   for I in A'Range(1) loop
-      for J in A'Range(2) loop
-         S (I) := S (I) + A (I, J);
-      end loop;
-   end loop;
-end Sum;
-@end example
-@end 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 @code{-gnatp} might well reveal cases where some checks do thwart
-vectorization.
-
-Type conversions may also prevent vectorization if they involve semantics that
-are not directly supported by the code generator or the SIMD instruction set.
-A typical example is direct conversion from floating-point to integer types.
-The solution in this case is to use the following idiom:
-
-@quotation
-
-@example
-Integer (S'Truncation (F))
-@end example
-@end quotation
-
-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
-static bounds:
-
-@quotation
-
-@example
-type Array_Type is array (1 .. 4) of Long_Float;
-@end example
-@end quotation
-
-constrained array types with dynamic bounds:
-
-@quotation
-
-@example
-type Array_Type is array (1 .. Q.N) of Long_Float;
-
-type Array_Type is array (Q.K .. 4) of Long_Float;
-
-type Array_Type is array (Q.K .. Q.N) of Long_Float;
-@end example
-@end quotation
-
-or unconstrained array types:
-
-@quotation
-
-@example
-type Array_Type is array (Positive range <>) of Long_Float;
-@end example
-@end quotation
-
-The quality of the generated code decreases when the dynamic aspect of the
-array type increases, the worst code being generated for unconstrained array
-types.  This is so because, the less information the compiler has about the
-bounds of the array, the more fallback code it needs to generate in order to
-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 @code{Loop_Optimize}:
-
-@quotation
-
-@example
-pragma Loop_Optimize (Vector);
-@end example
-@end quotation
-
-placed immediately within the loop will convey the appropriate hint to the
-compiler for this loop.
-
-It is also possible to help the compiler generate better vectorized code
-for a given loop by asserting that there are no loop-carried dependencies
-in the loop.  Consider for example the procedure:
-
-@quotation
-
-@example
-type Arr is array (1 .. 4) of Long_Float;
-
-procedure Add (X, Y : not null access Arr; R : not null access Arr) is
-begin
-  for I in Arr'Range loop
-    R(I) := X(I) + Y(I);
-  end loop;
-end;
-@end example
-@end quotation
-
-By default, the compiler cannot unconditionally vectorize the loop because
-assigning to a component of the array designated by R in one iteration could
-change the value read from the components of the array designated by X or Y
-in a later iteration.  As a result, the compiler will generate two versions
-of the loop in the object code, one vectorized and the other not vectorized,
-as well as a test to select the appropriate version at run time.  This can
-be overcome by another hint:
-
-@quotation
-
-@example
-pragma Loop_Optimize (Ivdep);
-@end example
-@end quotation
-
-placed immediately within the loop will tell the compiler that it can safely
-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 id35}@anchor{18a}@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{18b}
-@subsubsection Other Optimization Switches
-
-
-@geindex Optimization 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 @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 `Submodel Options' section in the `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 id36}@anchor{18c}@anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{e4}
-@subsubsection Optimization and Strict Aliasing
-
-
-@geindex Aliasing
-
-@geindex Strict Aliasing
-
-@geindex No_Strict_Aliasing
-
-The strong typing capabilities of Ada allow an optimizer to generate
-efficient code in situations where other languages would be forced to
-make worst case assumptions preventing such optimizations. Consider
-the following example:
-
-@quotation
-
-@example
-procedure R is
-   type Int1 is new Integer;
-   type Int2 is new Integer;
-   type Int1A is access Int1;
-   type Int2A is access Int2;
-   Int1V : Int1A;
-   Int2V : Int2A;
-   ...
-
-begin
-   ...
-   for J in Data'Range loop
-      if Data (J) = Int1V.all then
-         Int2V.all := Int2V.all + 1;
-      end if;
-   end loop;
-   ...
-end R;
-@end example
-@end quotation
-
-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 @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 @code{Unchecked_Conversion} are used to break
-the typing system. Consider the following complete program example:
-
-@quotation
-
-@example
-package p1 is
-   type int1 is new integer;
-   type int2 is new integer;
-   type a1 is access int1;
-   type a2 is access int2;
-end p1;
-
-with p1; use p1;
-package p2 is
-   function to_a2 (Input : a1) return a2;
-end p2;
-
-with Ada.Unchecked_Conversion;
-package body p2 is
-   function to_a2 (Input : a1) return a2 is
-      function to_a2u is
-        new Ada.Unchecked_Conversion (a1, a2);
-   begin
-      return to_a2u (Input);
-   end to_a2;
-end p2;
-
-with p2; use p2;
-with p1; use p1;
-with Text_IO; use Text_IO;
-procedure m is
-   v1 : a1 := new int1;
-   v2 : a2 := to_a2 (v1);
-begin
-   v1.all := 1;
-   v2.all := 0;
-   put_line (int1'image (v1.all));
-end;
-@end example
-@end quotation
-
-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 @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
-the Ada RM specifies that an unchecked conversion where the resulting
-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 @code{int2}.  This means that the
-effect is entirely unpredictable.
-
-However, although that explanation may satisfy a language
-lawyer, in practice an applications programmer expects an
-unchecked conversion involving pointers to create true
-aliases and the behavior of printing 1 seems plain wrong.
-In this case, the strict aliasing optimization is unwelcome.
-
-Indeed the compiler recognizes this possibility, and the
-unchecked conversion generates a warning:
-
-@quotation
-
-@example
-p2.adb:5:07: warning: possible aliasing problem with type "a2"
-p2.adb:5:07: warning: use -fno-strict-aliasing switch for references
-p2.adb:5:07: warning:  or use "pragma No_Strict_Aliasing (a2);"
-@end example
-@end quotation
-
-Unfortunately the problem is recognized when compiling the body of
-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 @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 @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 @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 @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 @code{No_Strict_Aliasing} with no parameters may be
-used to specify that for all access types, the strict
-aliasing optimization should be suppressed.
-
-However, these approaches are still overkill, in that they causes
-all manipulations of all access values to be deoptimized. A more
-refined approach is to concentrate attention on the specific
-access type identified as problematic.
-
-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 @code{Unchecked_Conversion} to turn
-the warning off:
-
-@quotation
-
-@example
-pragma Warnings (Off);
-function to_a2u is
-  new Ada.Unchecked_Conversion (a1, a2);
-pragma Warnings (On);
-@end example
-@end quotation
-
-Of course that approach is not appropriate for this particular
-example, since indeed there is a problematic reference. In this
-case we can take one of two other approaches.
-
-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
-@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
-is automatically suppressed for the type.
-
-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
-@code{No_Strict_Aliasing} for the type. This pragma must occur in the
-same declarative sequence as the declaration of the access type:
-
-@quotation
-
-@example
-type a2 is access int2;
-pragma No_Strict_Aliasing (a2);
-@end example
-@end quotation
-
-Here again, the compiler now knows that the strict aliasing optimization
-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
-simple cases of unchecked conversions, there are tricker and more
-indirect ways of creating type incorrect aliases which the compiler
-cannot detect. Examples are the use of address overlays and unchecked
-conversions involving composite types containing access types as
-components. In such cases, no warnings are generated, but there can
-still be aliasing problems. One safe coding practice is to forbid the
-use of address clauses for type overlaying, and to allow unchecked
-conversion only for primitive types. This is not really a significant
-restriction since any possible desired effect can be achieved by
-unchecked conversion of access values.
-
-The aliasing analysis done in strict aliasing mode can certainly
-have significant benefits. We have seen cases of large scale
-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
-@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 @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
-@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{18d}@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{18e}
-@subsubsection Aliased Variables and Optimization
-
-
-@geindex Aliasing
-
-There are scenarios in which programs may
-use low level techniques to modify variables
-that otherwise might be considered to be unassigned. For example,
-a variable can be passed to a procedure by reference, which takes
-the address of the parameter and uses the address to modify the
-variable’s value, even though it is passed as an IN parameter.
-Consider the following example:
-
-@quotation
-
-@example
-procedure P is
-   Max_Length : constant Natural := 16;
-   type Char_Ptr is access all Character;
-
-   procedure Get_String(Buffer: Char_Ptr; Size : Integer);
-   pragma Import (C, Get_String, "get_string");
-
-   Name : aliased String (1 .. Max_Length) := (others => ' ');
-   Temp : Char_Ptr;
-
-   function Addr (S : String) return Char_Ptr is
-      function To_Char_Ptr is
-        new Ada.Unchecked_Conversion (System.Address, Char_Ptr);
-   begin
-      return To_Char_Ptr (S (S'First)'Address);
-   end;
-
-begin
-   Temp := Addr (Name);
-   Get_String (Temp, Max_Length);
-end;
-@end example
-@end quotation
-
-where Get_String is a C function that uses the address in Temp to
-modify the variable @code{Name}. This code is dubious, and arguably
-erroneous, and the compiler would be entitled to assume that
-@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
-levels of optimization.
-
-What the compiler does for such cases is to assume that marking
-a variable as aliased indicates that some “funny business” may
-be going on. The optimizer recognizes the aliased keyword and
-inhibits optimizations that assume the value cannot be assigned.
-This means that the above example will in fact “work” reliably,
-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{18f}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{190}
-@subsubsection Atomic Variables and Optimization
-
-
-@geindex Atomic
-
-There are two considerations with regard to performance when
-atomic variables are used.
-
-First, the RM only guarantees that access to atomic variables
-be atomic, it has nothing to say about how this is achieved,
-though there is a strong implication that this should not be
-achieved by explicit locking code. Indeed GNAT will never
-generate any locking code for atomic variable access (it will
-simply reject any attempt to make a variable or type atomic
-if the atomic access cannot be achieved without such locking code).
-
-That being said, it is important to understand that you cannot
-assume that the entire variable will always be accessed. Consider
-this example:
-
-@quotation
-
-@example
-type R is record
-   A,B,C,D : Character;
-end record;
-for R'Size use 32;
-for R'Alignment use 4;
-
-RV : R;
-pragma Atomic (RV);
-X : Character;
-...
-X := RV.B;
-@end example
-@end quotation
-
-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
-is still atomic, which is all the RM requires. GNAT can and does take
-advantage of this, depending on the architecture and optimization level.
-Any assumption to the contrary is non-portable and risky. Even if you
-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 @code{RV} in this
-example be full 32-bit loads, you need to make a copy for the access
-as in:
-
-@quotation
-
-@example
-declare
-   RV_Copy : constant R := RV;
-begin
-   X := RV_Copy.B;
-end;
-@end example
-@end quotation
-
-Now the reference to RV must read the whole variable.
-Actually one can imagine some compiler which figures
-out that the whole copy is not required (because only
-the B field is actually accessed), but GNAT
-certainly won’t do that, and we don’t know of any
-compiler that would not handle this right, and the
-above code will in practice work portably across
-all architectures (that permit the Atomic declaration).
-
-The second issue with atomic variables has to do with
-the possible requirement of generating synchronization
-code. For more details on this, consult the sections on
-the pragmas Enable/Disable_Atomic_Synchronization in the
-GNAT Reference Manual. If performance is critical, and
-such synchronization code is not required, it may be
-useful to disable it.
-
-@node Passive Task Optimization,,Atomic Variables and Optimization,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{191}@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{192}
-@subsubsection Passive Task Optimization
-
-
-@geindex Passive Task
-
-A passive task is one which is sufficiently simple that
-in theory a compiler could recognize it an implement it
-efficiently without creating a new thread. The original design
-of Ada 83 had in mind this kind of passive task optimization, but
-only a few Ada 83 compilers attempted it. The problem was that
-it was difficult to determine the exact conditions under which
-the optimization was possible. The result is a very fragile
-optimization where a very minor change in the program can
-suddenly silently make a task non-optimizable.
-
-With the revisiting of this issue in Ada 95, there was general
-agreement that this approach was fundamentally flawed, and the
-notion of protected types was introduced. When using protected
-types, the restrictions are well defined, and you KNOW that the
-operations will be optimized, and furthermore this optimized
-performance is fully portable.
-
-Although it would theoretically be possible for GNAT to attempt to
-do this optimization, but it really doesn’t make sense in the
-context of Ada 95, and none of the Ada 95 compilers implement
-this optimization as far as we know. In particular GNAT never
-attempts to perform this optimization.
-
-In any new Ada 95 code that is written, you should always
-use protected types in place of tasks that might be able to
-be optimized in this manner.
-Of course this does not help if you have legacy Ada 83 code
-that depends on this optimization, but it is unusual to encounter
-a case where the performance gains from this optimization
-are significant.
-
-Your program should work correctly without this optimization. If
-you have performance problems, then the most practical
-approach is to figure out exactly where these performance problems
-arise, and update those particular tasks to be protected types. Note
-that typically clients of the tasks who call entries, will not have
-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 id40}@anchor{193}@anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{194}
-@subsection @code{Text_IO} Suggestions
-
-
-@geindex Text_IO and performance
-
-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 @code{Stream_IO} instead of
-@code{Text_IO} for volume output, since this package has less overhead.
-
-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 `tail -f' command to watch redirected output).
-
-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 @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 id41}@anchor{195}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{196}
-@subsection Reducing Size of Executables with Unused Subprogram/Data Elimination
-
-
-@geindex Uunused subprogram/data elimination
-
-This section describes how you can eliminate unused subprograms and data from
-your executable just by setting options at compilation time.
-
-@menu
-* About unused subprogram/data elimination:: 
-* Compilation options:: 
-* Example of 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 about-unused-subprogram-data-elimination}@anchor{197}@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{198}
-@subsubsection About unused subprogram/data elimination
-
-
-By default, an executable contains all code and data of its composing objects
-(directly linked or coming from statically linked libraries), even data or code
-never used by this executable.
-
-This feature will allow you to eliminate such unused code from your
-executable, making it smaller (in disk and in memory).
-
-This functionality is available on all Linux platforms except for the IA-64
-architecture and on all cross platforms using the ELF binary file format.
-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 compilation-options}@anchor{199}@anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{19a}
-@subsubsection Compilation options
-
-
-The operation of eliminating the unused code and data from the final executable
-is directly performed by the linker.
-
-@geindex -ffunction-sections (gcc)
-
-@geindex -fdata-sections (gcc)
-
-In order to do this, it has to work with objects compiled with the
-following options:
-@code{-ffunction-sections} @code{-fdata-sections}.
-
-These options are usable with C and Ada files.
-They will place respectively each
-function or data in a separate section in the resulting object file.
-
-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 @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 (@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 @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).
-
-The GNAT static library is now compiled with -ffunction-sections and
--fdata-sections on some platforms. This allows you to eliminate the unused code
-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 example-of-unused-subprogram-data-elimination}@anchor{19b}@anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{19c}
-@subsubsection Example of unused subprogram/data elimination
-
-
-Here is a simple example:
-
-@quotation
-
-@example
-with Aux;
-
-procedure Test is
-begin
-   Aux.Used (10);
-end Test;
-
-package Aux is
-   Used_Data   : Integer;
-   Unused_Data : Integer;
-
-   procedure Used   (Data : Integer);
-   procedure Unused (Data : Integer);
-end Aux;
-
-package body Aux is
-   procedure Used (Data : Integer) is
-   begin
-      Used_Data := Data;
-   end Used;
-
-   procedure Unused (Data : Integer) is
-   begin
-      Unused_Data := Data;
-   end Unused;
-end Aux;
-@end example
-@end quotation
-
-@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
-
-@example
-$ gnatmake test
-
-$ nm test | grep used
-020015f0 T aux__unused
-02005d88 B aux__unused_data
-020015cc T aux__used
-02005d84 B aux__used_data
-
-$ gnatmake test -cargs -fdata-sections -ffunction-sections \\
-     -largs -Wl,--gc-sections
-
-$ nm test | grep used
-02005350 T aux__used
-0201ffe0 B aux__used_data
-@end example
-@end quotation
-
-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
-
-@geindex Checks (overflow)
-
-@node Overflow Check Handling in GNAT,Performing Dimensionality Analysis in GNAT,Improving Performance,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id45}@anchor{149}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{19d}
-@section Overflow Check Handling in GNAT
-
-
-This section explains how to control the handling of overflow checks.
-
-@menu
-* Background:: 
-* Management of Overflows in GNAT:: 
-* Specifying the Desired Mode:: 
-* Default Settings:: 
-* Implementation Notes:: 
-
-@end menu
-
-@node Background,Management of Overflows in GNAT,,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{19f}
-@subsection Background
-
-
-Overflow checks are checks that the compiler may make to ensure
-that intermediate results are not out of range. For example:
-
-@quotation
-
-@example
-A : Integer;
-...
-A := A + 1;
-@end example
-@end quotation
-
-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:
-
-@quotation
-
-@example
-A, C : Integer;
-...
-A := (A + 1) + C;
-@end example
-@end quotation
-
-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
-@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
-it up to the implementation to do one of two things if overflow
-checks are enabled.
-
-
-@itemize *
-
-@item 
-raise an exception (@code{Constraint_Error}), or
-
-@item 
-yield the correct mathematical result which is then used in
-subsequent operations.
-@end itemize
-
-If the compiler chooses the first approach, then the assignment of this
-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
-chooses the second approach, then it can perform both additions yielding
-the correct mathematical result, which is in range, so no exception
-will be raised, and the right result is obtained, regardless of whether
-overflow checks are suppressed.
-
-Note that in the first example an
-exception will be raised in either case, since if the compiler
-gives the correct mathematical result for the addition, it will
-be out of range of the target type of the assignment, and thus
-fails the range check.
-
-This lack of specified behavior in the handling of overflow for
-intermediate results is a source of non-portability, and can thus
-be problematic when programs are ported. Most typically this arises
-in a situation where the original compiler did not raise an exception,
-and then the application is moved to a compiler where the check is
-performed on the intermediate result and an unexpected exception is
-raised.
-
-Furthermore, when using Ada 2012’s preconditions and other
-assertion forms, another issue arises. Consider:
-
-@quotation
-
-@example
-procedure P (A, B : Integer) with
-  Pre => A + B <= Integer'Last;
-@end example
-@end quotation
-
-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 @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 @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:
-
-@quotation
-
-@example
-procedure Q (A, B, C : Integer) with
-  Pre => A + B + C <= Integer'Last;
-@end example
-@end quotation
-
-Consider the call
-
-@quotation
-
-@example
-Q (A => Integer'Last, B => 1, C => -1);
-@end example
-@end quotation
-
-From a mathematical point of view the precondition
-is True, but at run time we may (but are not guaranteed to) get an
-exception raised because of the intermediate overflow (and we really
-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 id47}@anchor{1a0}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{1a1}
-@subsection Management of Overflows in GNAT
-
-
-To deal with the portability issue, and with the problem of
-mathematical versus run-time interpretation of the expressions in
-assertions, GNAT provides comprehensive control over the handling
-of intermediate overflow. GNAT can operate in three modes, and
-furthermore, permits separate selection of operating modes for
-the expressions within assertions (here the term ‘assertions’
-is used in the technical sense, which includes preconditions and so forth)
-and for expressions appearing outside assertions.
-
-The three modes are:
-
-
-@itemize *
-
-@item 
-`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
-be in range of the base type. If this is not the
-case then either an exception is raised (if overflow checks are
-enabled) or the execution is erroneous (if overflow checks are suppressed).
-This is the normal default mode.
-
-@item 
-`Most intermediate overflows avoided' (@code{MINIMIZED})
-
-In this mode, the compiler attempts to avoid intermediate overflows by
-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
-run time (compared to suppressing intermediate overflow checks), though
-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
-@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 @code{Long_Long_Integer} is not large
-enough, consider the following example:
-
-@quotation
-
-@example
-procedure R (A, B, C, D : Integer) with
-  Pre => (A**2 * B**2) / (C**2 * D**2) <= 10;
-@end example
-@end quotation
-
-where @code{A} = @code{B} = @code{C} = @code{D} = @code{Integer'Last}.
-Now the intermediate results are
-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
-says `most' intermediate overflows are avoided). In this case,
-an exception is raised if overflow checks are enabled, and the
-execution is erroneous if overflow checks are suppressed.
-
-@item 
-`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 @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.
-
-This mode has the advantage of avoiding any intermediate
-overflows, but at the expense of significant run-time overhead,
-including the use of a library (included automatically in this
-mode) for multiple-precision arithmetic.
-
-This mode provides cleaner semantics for assertions, since now
-the run-time behavior emulates true arithmetic behavior for the
-predefined arithmetic operators, meaning that there is never a
-conflict between the mathematical view of the assertion, and its
-run-time behavior.
-
-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
-@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
-
-Note that these modes apply only to the evaluation of predefined
-arithmetic, membership, and comparison operators for signed integer
-arithmetic.
-
-For fixed-point arithmetic, checks can be suppressed. But if checks
-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 @code{STRICT} mode).
-
-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
-constrained floating-point type, and range checks will be carried
-out in the normal manner (with infinite values always failing all
-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 id48}@anchor{1a2}@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{e9}
-@subsection Specifying the Desired Mode
-
-
-@geindex pragma Overflow_Mode
-
-The desired mode of for handling intermediate overflow can be specified using
-either the @code{Overflow_Mode} pragma or an equivalent compiler switch.
-The pragma has the form
-
-@quotation
-
-@example
-pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]);
-@end example
-@end quotation
-
-where @code{MODE} is one of
-
-
-@itemize *
-
-@item 
-@code{STRICT}:  intermediate overflows checked (using base type)
-
-@item 
-@code{MINIMIZED}: minimize intermediate overflows
-
-@item 
-@code{ELIMINATED}: eliminate intermediate overflows
-@end itemize
-
-The case is ignored, so @code{MINIMIZED}, @code{Minimized} and
-@code{minimized} all have the same effect.
-
-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 @code{General} applies to expressions outside assertions,
-and @code{Assertions} applies to expressions within assertions. For example:
-
-@quotation
-
-@example
-pragma Overflow_Mode
-  (General => Minimized, Assertions => Eliminated);
-@end example
-@end quotation
-
-specifies that general expressions outside assertions be evaluated
-in ‘minimize intermediate overflows’ mode, and expressions within
-assertions be evaluated in ‘eliminate intermediate overflows’ mode.
-This is often a reasonable choice, avoiding excessive overhead
-outside assertions, but assuring a high degree of portability
-when importing code from another compiler, while incurring
-the extra overhead for assertion expressions to ensure that
-the behavior at run time matches the expected mathematical
-behavior.
-
-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 @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 @code{Suppress}
-or @code{Unsuppress} in the usual manner.
-
-@geindex -gnato? (gcc)
-
-@geindex -gnato?? (gcc)
-
-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).
-
-Here @code{?} is one of the digits @code{1} through @code{3}:
-
-@quotation
-
-
-@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@item
-
-@code{1}
-
-@tab
-
-use base type for intermediate operations (@code{STRICT})
-
-@item
-
-@code{2}
-
-@tab
-
-minimize intermediate overflows (@code{MINIMIZED})
-
-@item
-
-@code{3}
-
-@tab
-
-eliminate intermediate overflows (@code{ELIMINATED})
-
-@end multitable
-
-@end quotation
-
-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
-@code{-gnato23}.
-
-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 (@code{STRICT} mode).
-
-@node Default Settings,Implementation Notes,Specifying the Desired Mode,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{1a3}@anchor{gnat_ugn/gnat_and_program_execution id49}@anchor{1a4}
-@subsection Default Settings
-
-
-The default mode for overflow checks is
-
-@quotation
-
-@example
-General => Strict
-@end example
-@end quotation
-
-which causes all computations both inside and outside assertions to use
-the base type.
-
-This retains compatibility with previous versions of
-GNAT which suppressed overflow checks by default and always
-used the base type for computation of intermediate results.
-
-@c Sphinx allows no emphasis within :index: role. As a workaround we
-@c point the index to "switch" and use emphasis for "-gnato".
-
-The 
-@geindex -gnato (gcc)
-switch @code{-gnato} (with no digits following)
-is equivalent to
-
-@quotation
-
-@example
-General => Strict
-@end example
-@end quotation
-
-which causes overflow checking of all intermediate overflows
-both inside and outside assertions against the base type.
-
-The pragma @code{Suppress (Overflow_Check)} disables overflow
-checking, but it has no effect on the method used for computing
-intermediate results.
-
-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 id50}@anchor{1a5}@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1a6}
-@subsection Implementation Notes
-
-
-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 (@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
-for code that is to be exported to some other compiler than GNAT.
-
-The Ada standard allows the reassociation of expressions at
-the same precedence level if no parentheses are present. For
-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 @code{A+B+C} will be evaluated as @code{(A+B)+C}.
-If you need the other order, you can write the parentheses
-explicitly @code{A+(B+C)} and GNAT will respect this order.
-
-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 @code{Long_Long_Integer} is sufficient to guard against
-intermediate overflows. This package does not use dynamic
-allocation, 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 @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 @code{[Long_[Long_]]Integer'Base}, which
-still has the same bounds as its associated constrained
-type at run-time.
-
-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 id51}@anchor{14a}@anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{1a7}
-@section Performing Dimensionality Analysis in GNAT
-
-
-@geindex Dimensionality analysis
-
-The GNAT compiler supports dimensionality checking. The user can
-specify physical units for objects, and the compiler will verify that uses
-of these objects are compatible with their dimensions, in a fashion that is
-familiar to engineering practice. The dimensions of algebraic expressions
-(including powers with static exponents) are computed from their constituents.
-
-@geindex Dimension_System aspect
-
-@geindex Dimension aspect
-
-This feature depends on Ada 2012 aspect specifications, and is available from
-version 7.0.1 of GNAT onwards.
-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 `Implementation Defined Aspects'
-chapter of the `GNAT Reference Manual').
-
-The major advantage of this model is that it does not require the declaration of
-multiple operators for all possible combinations of types: it is only necessary
-to use the proper subtypes in object declarations.
-
-@geindex System.Dim.Mks package (GNAT library)
-
-@geindex MKS_Type type
-
-The simplest way to impose dimensionality checking on a computation is to make
-use of one of the instantiations of the package @code{System.Dim.Generic_Mks}, which
-are part of the GNAT library. This generic 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 package, in file
-@code{s-digemk.ads}.
-
-@quotation
-
-@geindex s-digemk.ads file
-
-@example
-type Mks_Type is new Float_Type
-  with
-   Dimension_System => (
-     (Unit_Name => Meter,    Unit_Symbol => 'm',   Dim_Symbol => 'L'),
-     (Unit_Name => Kilogram, Unit_Symbol => "kg",  Dim_Symbol => 'M'),
-     (Unit_Name => Second,   Unit_Symbol => 's',   Dim_Symbol => 'T'),
-     (Unit_Name => Ampere,   Unit_Symbol => 'A',   Dim_Symbol => 'I'),
-     (Unit_Name => Kelvin,   Unit_Symbol => 'K',   Dim_Symbol => "Theta"),
-     (Unit_Name => Mole,     Unit_Symbol => "mol", Dim_Symbol => 'N'),
-     (Unit_Name => Candela,  Unit_Symbol => "cd",  Dim_Symbol => 'J'));
-@end example
-@end quotation
-
-The package then defines a series of subtypes that correspond to these
-conventional units. For example:
-
-@quotation
-
-@example
-subtype Length is Mks_Type
-  with
-   Dimension => (Symbol => 'm', Meter  => 1, others => 0);
-@end example
-@end quotation
-
-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:
-
-@quotation
-
-@example
-m   : constant Length           := 1.0;
-kg  : constant Mass             := 1.0;
-s   : constant Time             := 1.0;
-A   : constant Electric_Current := 1.0;
-@end example
-@end quotation
-
-as well as useful multiples of these units:
-
-@quotation
-
-@example
- cm  : constant Length := 1.0E-02;
- g   : constant Mass   := 1.0E-03;
- min : constant Time   := 60.0;
- day : constant Time   := 60.0 * 24.0 * min;
-...
-@end example
-@end quotation
-
-There are three instantiations of @code{System.Dim.Generic_Mks} defined in the
-GNAT library:
-
-
-@itemize *
-
-@item 
-@code{System.Dim.Float_Mks} based on @code{Float} defined in @code{s-diflmk.ads}.
-
-@item 
-@code{System.Dim.Long_Mks} based on @code{Long_Float} defined in @code{s-dilomk.ads}.
-
-@item 
-@code{System.Dim.Mks} based on @code{Long_Long_Float} defined in @code{s-dimmks.ads}.
-@end itemize
-
-Using one of these packages, you can then define a derived unit by providing
-the aspect that specifies its dimensions within the MKS system, as well as the
-string to be used for output of a value of that unit:
-
-@quotation
-
-@example
-subtype Acceleration is Mks_Type
-  with Dimension => ("m/sec^2",
-                     Meter => 1,
-                     Second => -2,
-                     others => 0);
-@end example
-@end quotation
-
-Here is a complete example of use:
-
-@quotation
-
-@example
-with System.Dim.MKS; use System.Dim.Mks;
-with System.Dim.Mks_IO; use System.Dim.Mks_IO;
-with Text_IO; use Text_IO;
-procedure Free_Fall is
-  subtype Acceleration is Mks_Type
-    with Dimension => ("m/sec^2", 1, 0, -2, others => 0);
-  G : constant acceleration := 9.81 * m / (s ** 2);
-  T : Time := 10.0*s;
-  Distance : Length;
-
-begin
-  Put ("Gravitational constant: ");
-  Put (G, Aft => 2, Exp => 0); Put_Line ("");
-  Distance := 0.5 * G * T ** 2;
-  Put ("distance travelled in 10 seconds of free fall ");
-  Put (Distance, Aft => 2, Exp => 0);
-  Put_Line ("");
-end Free_Fall;
-@end example
-@end quotation
-
-Execution of this program yields:
-
-@quotation
-
-@example
-Gravitational constant:  9.81 m/sec^2
-distance travelled in 10 seconds of free fall 490.50 m
-@end example
-@end quotation
-
-However, incorrect assignments such as:
-
-@quotation
-
-@example
-Distance := 5.0;
-Distance := 5.0 * kg;
-@end example
-@end quotation
-
-are rejected with the following diagnoses:
-
-@quotation
-
-@example
-Distance := 5.0;
-   >>> dimensions mismatch in assignment
-   >>> left-hand side has dimension [L]
-   >>> right-hand side is dimensionless
-
-Distance := 5.0 * kg:
-   >>> dimensions mismatch in assignment
-   >>> left-hand side has dimension [L]
-   >>> right-hand side has dimension [M]
-@end example
-@end quotation
-
-The dimensions of an expression are properly displayed, even if there is
-no explicit subtype for it. If we add to the program:
-
-@quotation
-
-@example
-Put ("Final velocity: ");
-Put (G * T, Aft =>2, Exp =>0);
-Put_Line ("");
-@end example
-@end quotation
-
-then the output includes:
-
-@quotation
-
-@example
-Final velocity: 98.10 m.s**(-1)
-@end example
-
-@geindex Dimensionable type
-
-@geindex Dimensioned subtype
-@end quotation
-
-The type @code{Mks_Type} is said to be a `dimensionable type' since it has a
-@code{Dimension_System} aspect, and the subtypes @code{Length}, @code{Mass}, etc.,
-are said to be `dimensioned subtypes' since each one has a @code{Dimension}
-aspect.
-
-@quotation
-
-@geindex Dimension Vector (for a dimensioned subtype)
-
-@geindex Dimension aspect
-
-@geindex Dimension_System aspect
-@end quotation
-
-The @code{Dimension} aspect of a dimensioned subtype @code{S} defines a mapping
-from the base type’s Unit_Names to integer (or, more generally, rational)
-values. This mapping is the `dimension vector' (also referred to as the
-`dimensionality') for that subtype, denoted by @code{DV(S)}, and thus for each
-object of that subtype. Intuitively, the value specified for each
-@code{Unit_Name} is the exponent associated with that unit; a zero value
-means that the unit is not used. For example:
-
-@quotation
-
-@example
-declare
-   Acc : Acceleration;
-   ...
-begin
-   ...
-end;
-@end example
-@end quotation
-
-Here @code{DV(Acc)} = @code{DV(Acceleration)} =
-@code{(Meter=>1, Kilogram=>0, Second=>-2, Ampere=>0, Kelvin=>0, Mole=>0, Candela=>0)}.
-Symbolically, we can express this as @code{Meter / Second**2}.
-
-The dimension vector of an arithmetic expression is synthesized from the
-dimension vectors of its components, with compile-time dimensionality checks
-that help prevent mismatches such as using an @code{Acceleration} where a
-@code{Length} is required.
-
-The dimension vector of the result of an arithmetic expression `expr', or
-@code{DV(@var{expr})}, is defined as follows, assuming conventional
-mathematical definitions for the vector operations that are used:
-
-
-@itemize *
-
-@item 
-If `expr' is of the type `universal_real', or is not of a dimensioned subtype,
-then `expr' is dimensionless; @code{DV(@var{expr})} is the empty vector.
-
-@item 
-@code{DV(@var{op expr})}, where `op' is a unary operator, is @code{DV(@var{expr})}
-
-@item 
-@code{DV(@var{expr1 op expr2})} where `op' is “+” or “-” is @code{DV(@var{expr1})}
-provided that @code{DV(@var{expr1})} = @code{DV(@var{expr2})}.
-If this condition is not met then the construct is illegal.
-
-@item 
-@code{DV(@var{expr1} * @var{expr2})} is @code{DV(@var{expr1})} + @code{DV(@var{expr2})},
-and @code{DV(@var{expr1} / @var{expr2})} = @code{DV(@var{expr1})} - @code{DV(@var{expr2})}.
-In this context if one of the `expr's is dimensionless then its empty
-dimension vector is treated as @code{(others => 0)}.
-
-@item 
-@code{DV(@var{expr} ** @var{power})} is `power' * @code{DV(@var{expr})},
-provided that `power' is a static rational value. If this condition is not
-met then the construct is illegal.
-@end itemize
-
-Note that, by the above rules, it is illegal to use binary “+” or “-” to
-combine a dimensioned and dimensionless value.  Thus an expression such as
-@code{acc-10.0} is illegal, where @code{acc} is an object of subtype
-@code{Acceleration}.
-
-The dimensionality checks for relationals use the same rules as
-for “+” and “-”, except when comparing to a literal; thus
-
-@quotation
-
-@example
-acc > len
-@end example
-@end quotation
-
-is equivalent to
-
-@quotation
-
-@example
-acc-len > 0.0
-@end example
-@end quotation
-
-and is thus illegal, but
-
-@quotation
-
-@example
-acc > 10.0
-@end example
-@end quotation
-
-is accepted with a warning. Analogously a conditional expression requires the
-same dimension vector for each branch (with no exception for literals).
-
-The dimension vector of a type conversion @code{T(@var{expr})} is defined
-as follows, based on the nature of @code{T}:
-
-
-@itemize *
-
-@item 
-If @code{T} is a dimensioned subtype then @code{DV(T(@var{expr}))} is @code{DV(T)}
-provided that either `expr' is dimensionless or
-@code{DV(T)} = @code{DV(@var{expr})}. The conversion is illegal
-if `expr' is dimensioned and @code{DV(@var{expr})} /= @code{DV(T)}.
-Note that vector equality does not require that the corresponding
-Unit_Names be the same.
-
-As a consequence of the above rule, it is possible to convert between
-different dimension systems that follow the same international system
-of units, with the seven physical components given in the standard order
-(length, mass, time, etc.). Thus a length in meters can be converted to
-a length in inches (with a suitable conversion factor) but cannot be
-converted, for example, to a mass in pounds.
-
-@item 
-If @code{T} is the base type for `expr' (and the dimensionless root type of
-the dimension system), then @code{DV(T(@var{expr}))} is @code{DV(expr)}.
-Thus, if `expr' is of a dimensioned subtype of @code{T}, the conversion may
-be regarded as a “view conversion” that preserves dimensionality.
-
-This rule makes it possible to write generic code that can be instantiated
-with compatible dimensioned subtypes.  The generic unit will contain
-conversions that will consequently be present in instantiations, but
-conversions to the base type will preserve dimensionality and make it
-possible to write generic code that is correct with respect to
-dimensionality.
-
-@item 
-Otherwise (i.e., @code{T} is neither a dimensioned subtype nor a dimensionable
-base type), @code{DV(T(@var{expr}))} is the empty vector. Thus a dimensioned
-value can be explicitly converted to a non-dimensioned subtype, which
-of course then escapes dimensionality analysis.
-@end itemize
-
-The dimension vector for a type qualification @code{T'(@var{expr})} is the same
-as for the type conversion @code{T(@var{expr})}.
-
-An assignment statement
-
-@quotation
-
-@example
-Source := Target;
-@end example
-@end quotation
-
-requires @code{DV(Source)} = @code{DV(Target)}, and analogously for parameter
-passing (the dimension vector for the actual parameter must be equal to the
-dimension vector for the formal parameter).
-
-@node Stack Related Facilities,Memory Management Issues,Performing Dimensionality Analysis in GNAT,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id52}@anchor{14b}@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{1a8}
-@section Stack Related Facilities
-
-
-This section describes some useful tools associated with stack
-checking and analysis. In
-particular, it deals with dynamic and static stack usage measurements.
-
-@menu
-* Stack Overflow Checking:: 
-* Static Stack Usage Analysis:: 
-* Dynamic Stack Usage Analysis:: 
-
-@end menu
-
-@node Stack Overflow Checking,Static Stack Usage Analysis,,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id53}@anchor{1a9}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{e5}
-@subsection Stack Overflow Checking
-
-
-@geindex Stack Overflow Checking
-
-@geindex -fstack-check (gcc)
-
-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
-adding a guard page at the end of each task stack. This mechanism is usually
-not enough for dealing properly with stack overflow situations because
-a large local variable could “jump” above the guard page.
-Furthermore, when the
-guard page is hit, there may not be any space left on the stack for executing
-the exception propagation code. Enabling stack checking avoids
-such situations.
-
-To activate stack checking, compile all units with the @code{gcc} option
-@code{-fstack-check}. For example:
-
-@quotation
-
-@example
-$ gcc -c -fstack-check package1.adb
-@end example
-@end 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 @code{Storage_Error} exception is raised.
-
-For declared tasks, the default stack size is defined by the GNAT runtime,
-whose size may be modified at bind time through the @code{-d} bind switch
-(@ref{110,,Switches for gnatbind}). Task specific stack sizes may be set using the
-@code{Storage_Size} pragma.
-
-For the environment task, the stack size is determined by the operating system.
-Consequently, to modify the size of the environment task please refer to your
-operating system documentation.
-
-@node Static Stack Usage Analysis,Dynamic Stack Usage Analysis,Stack Overflow Checking,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id54}@anchor{1aa}@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{e6}
-@subsection Static Stack Usage Analysis
-
-
-@geindex Static Stack Usage Analysis
-
-@geindex -fstack-usage
-
-A unit compiled with @code{-fstack-usage} will generate an extra file
-that specifies
-the maximum amount of stack used, on a per-function basis.
-The file has the same
-basename as the target object file with a @code{.su} extension.
-Each line of this file is made up of three fields:
-
-
-@itemize *
-
-@item 
-The name of the function.
-
-@item 
-A number of bytes.
-
-@item 
-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 @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 @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  @code{bounded}, it
-means that the second field is a reliable maximum of the function stack
-utilization.
-
-A unit compiled with @code{-Wstack-usage} will issue a warning for each
-subprogram whose stack usage might be larger than the specified amount of
-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 dynamic-stack-usage-analysis}@anchor{113}@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{1ab}
-@subsection Dynamic Stack Usage Analysis
-
-
-It is possible to measure the maximum amount of stack used by a task, by
-adding a switch to @code{gnatbind}, as:
-
-@quotation
-
-@example
-$ gnatbind -u0 file
-@end example
-@end quotation
-
-With this option, at each task termination, its stack usage is output on
-@code{stderr}.
-Note that this switch is not compatible with tools like
-Valgrind and DrMemory; they will report errors.
-
-It is not always convenient to output the stack usage when the program
-is still running. Hence, it is possible to delay this output until program
-termination. for a given number of tasks specified as the argument of the
-@code{-u} option. For instance:
-
-@quotation
-
-@example
-$ gnatbind -u100 file
-@end example
-@end quotation
-
-will buffer the stack usage information of the first 100 tasks to terminate and
-output this info at program termination. Results are displayed in four
-columns:
-
-@quotation
-
-@example
-Index | Task Name | Stack Size | Stack Usage
-@end example
-@end quotation
-
-where:
-
-
-@itemize *
-
-@item 
-`Index' is a number associated with each task.
-
-@item 
-`Task Name' is the name of the task analyzed.
-
-@item 
-`Stack Size' is the maximum size for the stack.
-
-@item 
-`Stack Usage' is the measure done by the stack analyzer.
-In order to prevent overflow, the stack
-is not entirely analyzed, and it’s not possible to know exactly how
-much has actually been used.
-@end itemize
-
-By default the environment task stack, the stack that contains the main unit,
-is not processed. To enable processing of the environment task stack, the
-environment variable GNAT_STACK_LIMIT needs to be set to the maximum size of
-the environment task stack. This amount is given in kilobytes. For example:
-
-@quotation
-
-@example
-$ set GNAT_STACK_LIMIT 1600
-@end example
-@end quotation
-
-would specify to the analyzer that the environment task stack has a limit
-of 1.6 megabytes. Any stack usage beyond this will be ignored by the analysis.
-
-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 id56}@anchor{14c}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{1ac}
-@section Memory Management Issues
-
-
-This section describes some useful memory pools provided in the GNAT library
-and in particular the GNAT Debug Pool facility, which can be used to detect
-incorrect uses of access values (including ‘dangling references’).
-
-
-@menu
-* Some Useful Memory Pools:: 
-* The GNAT Debug Pool Facility:: 
-
-@end menu
-
-@node Some Useful Memory Pools,The GNAT Debug Pool Facility,,Memory Management Issues
-@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{1ad}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{1ae}
-@subsection Some Useful Memory Pools
-
-
-@geindex Memory Pool
-
-@geindex storage
-@geindex pool
-
-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
-behavior. That is why this storage pool is used  when the user
-manages to make the default implicit allocator explicit as in this example:
-
-@quotation
-
-@example
-type T1 is access Something;
- -- no Storage pool is defined for T2
-
-type T2 is access Something_Else;
-for T2'Storage_Pool use T1'Storage_Pool;
--- the above is equivalent to
-for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object;
-@end example
-@end quotation
-
-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
-provided by several Ada 83 compilers for allocations performed through a local
-access type and whose purpose was to reclaim memory when exiting the
-scope of a given local access. As an example, the following program does not
-leak memory even though it does not perform explicit deallocation:
-
-@quotation
-
-@example
-with System.Pool_Local;
-procedure Pooloc1 is
-   procedure Internal is
-      type A is access Integer;
-      X : System.Pool_Local.Unbounded_Reclaim_Pool;
-      for A'Storage_Pool use X;
-      v : A;
-   begin
-      for I in  1 .. 50 loop
-         v := new Integer;
-      end loop;
-   end Internal;
-begin
-   for I in  1 .. 100 loop
-      Internal;
-   end loop;
-end Pooloc1;
-@end example
-@end quotation
-
-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
-access type is defined. This package is not intended to be used directly by the
-user and it is implicitly used for each such declaration:
-
-@quotation
-
-@example
-type T1 is access Something;
-for T1'Storage_Size use 10_000;
-@end example
-@end quotation
-
-@node The GNAT Debug Pool Facility,,Some Useful Memory Pools,Memory Management Issues
-@anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{1af}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{1b0}
-@subsection The GNAT Debug Pool Facility
-
-
-@geindex Debug Pool
-
-@geindex storage
-@geindex pool
-@geindex memory corruption
-
-The use of unchecked deallocation and unchecked conversion can easily
-lead to incorrect memory references. The problems generated by such
-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 @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
-related to suspected memory problems. See Ada Reference Manual 13.11.
-
-@quotation
-
-@example
-type Ptr is access Some_Type;
-Pool : GNAT.Debug_Pools.Debug_Pool;
-for Ptr'Storage_Pool use Pool;
-@end example
-@end quotation
-
-@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 @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
-values of the type may raise four distinct exceptions,
-which correspond to four potential kinds of memory corruption:
-
-
-@itemize *
-
-@item 
-@code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage}
-
-@item 
-@code{GNAT.Debug_Pools.Accessing_Deallocated_Storage}
-
-@item 
-@code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage}
-
-@item 
-@code{GNAT.Debug_Pools.Freeing_Deallocated_Storage}
-@end itemize
-
-For types associated with a Debug_Pool, dynamic allocation is performed using
-the standard GNAT allocation routine. References to all allocated chunks of
-memory are kept in an internal dictionary. Several deallocation strategies are
-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: @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
-@code{Debug_Pools}, that includes typical instances of  memory corruption:
-
-@quotation
-
-@example
-with GNAT.IO; use GNAT.IO;
-with Ada.Unchecked_Deallocation;
-with Ada.Unchecked_Conversion;
-with GNAT.Debug_Pools;
-with System.Storage_Elements;
-with Ada.Exceptions; use Ada.Exceptions;
-procedure Debug_Pool_Test is
-
-   type T is access Integer;
-   type U is access all T;
-
-   P : GNAT.Debug_Pools.Debug_Pool;
-   for T'Storage_Pool use P;
-
-   procedure Free is new Ada.Unchecked_Deallocation (Integer, T);
-   function UC is new Ada.Unchecked_Conversion (U, T);
-   A, B : aliased T;
-
-   procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line);
-
-begin
-   Info (P);
-   A := new Integer;
-   B := new Integer;
-   B := A;
-   Info (P);
-   Free (A);
-   begin
-      Put_Line (Integer'Image(B.all));
-   exception
-      when E : others => Put_Line ("raised: " & Exception_Name (E));
-   end;
-   begin
-      Free (B);
-   exception
-      when E : others => Put_Line ("raised: " & Exception_Name (E));
-   end;
-   B := UC(A'Access);
-   begin
-      Put_Line (Integer'Image(B.all));
-   exception
-      when E : others => Put_Line ("raised: " & Exception_Name (E));
-   end;
-   begin
-      Free (B);
-   exception
-      when E : others => Put_Line ("raised: " & Exception_Name (E));
-   end;
-   Info (P);
-end Debug_Pool_Test;
-@end example
-@end quotation
-
-The debug pool mechanism provides the following precise diagnostics on the
-execution of this erroneous program:
-
-@quotation
-
-@example
-Debug Pool info:
-  Total allocated bytes :  0
-  Total deallocated bytes :  0
-  Current Water Mark:  0
-  High Water Mark:  0
-
-Debug Pool info:
-  Total allocated bytes :  8
-  Total deallocated bytes :  0
-  Current Water Mark:  8
-  High Water Mark:  8
-
-raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE
-raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE
-raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE
-raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE
-Debug Pool info:
-  Total allocated bytes :  8
-  Total deallocated bytes :  4
-  Current Water Mark:  4
-  High Water Mark:  8
-@end example
-@end quotation
-
-
-@c -- Non-breaking space in running text
-@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 doc}@anchor{1b1}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1b2}@anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{d}
-@chapter Platform-Specific Information
-
-
-This appendix contains information relating to the implementation
-of run-time libraries on various platforms and also covers
-topics related to the GNAT implementation on Windows and Mac OS.
-
-@menu
-* Run-Time Libraries:: 
-* Specifying a Run-Time Library:: 
-* GNU/Linux Topics:: 
-* Microsoft Windows Topics:: 
-* Mac OS Topics:: 
-
-@end menu
-
-@node Run-Time Libraries,Specifying a Run-Time Library,,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information id2}@anchor{1b3}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{1b4}
-@section Run-Time Libraries
-
-
-@geindex Tasking and threads libraries
-
-@geindex Threads libraries and tasking
-
-@geindex Run-time libraries (platform-specific information)
-
-The GNAT run-time implementation may vary with respect to both the
-underlying threads library and the exception-handling scheme.
-For threads support, the default run-time will bind to the thread
-package of the underlying operating system.
-
-For exception handling, either or both of two models are supplied:
-
-@quotation
-
-@geindex Zero-Cost Exceptions
-
-@geindex ZCX (Zero-Cost Exceptions)
-@end quotation
-
-
-@itemize *
-
-@item 
-`Zero-Cost Exceptions' (“ZCX”),
-which uses binder-generated tables that
-are interrogated at run time to locate a handler.
-
-@geindex setjmp/longjmp Exception Model
-
-@geindex SJLJ (setjmp/longjmp Exception Model)
-
-@item 
-`setjmp / longjmp' (‘SJLJ’),
-which uses dynamically-set data to establish
-the set of handlers
-@end itemize
-
-Most programs should experience a substantial speed improvement by
-being compiled with a ZCX run-time.
-This is especially true for
-tasking applications or applications with many exception handlers.
-Note however that the ZCX run-time does not support asynchronous abort
-of tasks (@code{abort} and @code{select-then-abort} constructs) and will instead
-implement abort by polling points in the runtime. You can also add additional
-polling points explicitly if needed in your application via @code{pragma
-Abort_Defer}.
-
-This section summarizes which combinations of threads and exception support
-are supplied on various GNAT platforms.
-
-@menu
-* Summary of Run-Time Configurations:: 
-
-@end menu
-
-@node Summary of Run-Time Configurations,,,Run-Time Libraries
-@anchor{gnat_ugn/platform_specific_information id3}@anchor{1b5}@anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{1b6}
-@subsection Summary of Run-Time Configurations
-
-
-
-@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
-@headitem
-
-Platform
-
-@tab
-
-Run-Time
-
-@tab
-
-Tasking
-
-@tab
-
-Exceptions
-
-@item
-
-GNU/Linux
-
-@tab
-
-rts-native
-(default)
-
-@tab
-
-pthread library
-
-@tab
-
-ZCX
-
-@item
-
-rts-sjlj
-
-@tab
-
-pthread library
-
-@tab
-
-SJLJ
-
-@item
-
-Windows
-
-@tab
-
-rts-native
-(default)
-
-@tab
-
-native Win32 threads
-
-@tab
-
-ZCX
-
-@item
-
-rts-sjlj
-
-@tab
-
-native Win32 threads
-
-@tab
-
-SJLJ
-
-@item
-
-Mac OS
-
-@tab
-
-rts-native
-
-@tab
-
-pthread library
-
-@tab
-
-ZCX
-
-@end multitable
-
-
-@node Specifying a Run-Time Library,GNU/Linux Topics,Run-Time Libraries,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information id4}@anchor{1b7}@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{1b8}
-@section Specifying a Run-Time Library
-
-
-The @code{adainclude} subdirectory containing the sources of the GNAT
-run-time library, and the @code{adalib} subdirectory containing the
-@code{ALI} files and the static and/or shared GNAT library, are located
-in the gcc target-dependent area:
-
-@quotation
-
-@example
-target=$prefix/lib/gcc/gcc-*dumpmachine*/gcc-*dumpversion*/
-@end example
-@end quotation
-
-As indicated above, on some platforms several run-time libraries are supplied.
-These libraries are installed in the target dependent area and
-contain a complete source and binary subdirectory. The detailed description
-below explains the differences between the different libraries in terms of
-their thread support.
-
-The default run-time library (when GNAT is installed) is `rts-native'.
-This default run-time is selected by the means of soft links.
-For example on x86-linux:
-
-@c --
-@c --  $(target-dir)
-@c --      |
-@c --      +--- adainclude----------+
-@c --      |                        |
-@c --      +--- adalib-----------+  |
-@c --      |                     |  |
-@c --      +--- rts-native       |  |
-@c --      |    |                |  |
-@c --      |    +--- adainclude <---+
-@c --      |    |                |
-@c --      |    +--- adalib <----+
-@c --      |
-@c --      +--- rts-sjlj
-@c --           |
-@c --           +--- adainclude
-@c --           |
-@c --           +--- adalib
-
-
-@example
-               $(target-dir)
-              __/ /      \ \___
-      _______/   /        \    \_________________
-     /          /          \                     \
-    /          /            \                     \
-ADAINCLUDE  ADALIB      rts-native             rts-sjlj
-   :          :            /    \                 /   \
-   :          :           /      \               /     \
-   :          :          /        \             /       \
-   :          :         /          \           /         \
-   +-------------> adainclude     adalib   adainclude   adalib
-              :                     ^
-              :                     :
-              +---------------------+
-
-              Run-Time Library Directory Structure
-   (Upper-case names and dotted/dashed arrows represent soft links)
-@end example
-
-If the `rts-sjlj' library is to be selected on a permanent basis,
-these soft links can be modified with the following commands:
-
-@quotation
-
-@example
-$ cd $target
-$ rm -f adainclude adalib
-$ ln -s rts-sjlj/adainclude adainclude
-$ ln -s rts-sjlj/adalib adalib
-@end example
-@end quotation
-
-Alternatively, you can specify @code{rts-sjlj/adainclude} in the file
-@code{$target/ada_source_path} and @code{rts-sjlj/adalib} in
-@code{$target/ada_object_path}.
-
-@geindex --RTS option
-
-Selecting another run-time library temporarily can be
-achieved by using the @code{--RTS} switch, e.g., @code{--RTS=sjlj}
-@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1b9}
-@geindex SCHED_FIFO scheduling policy
-
-@geindex SCHED_RR scheduling policy
-
-@geindex SCHED_OTHER scheduling policy
-
-@menu
-* Choosing the Scheduling Policy:: 
-
-@end menu
-
-@node Choosing the Scheduling Policy,,,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information id5}@anchor{1ba}
-@subsection Choosing the Scheduling Policy
-
-
-When using a POSIX threads implementation, you have a choice of several
-scheduling policies: @code{SCHED_FIFO}, @code{SCHED_RR} and @code{SCHED_OTHER}.
-
-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 -T0 option
-
-@geindex pragma Task_Dispatching_Policy
-
-By default, GNAT uses the @code{SCHED_OTHER} policy. To specify
-@code{SCHED_FIFO},
-you can use one of the following:
-
-
-@itemize *
-
-@item 
-@code{pragma Time_Slice (0.0)}
-
-@item 
-the corresponding binder option @code{-T0}
-
-@item 
-@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)}
-@end itemize
-
-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
-this in a library package body in your application:
-
-@quotation
-
-@example
-function geteuid return Integer;
-pragma Import (C, geteuid, "geteuid");
-Ignore : constant Boolean :=
-  (if geteuid = 0 then True else raise Program_Error with "must be root");
-@end example
-@end quotation
-
-It gets the effective user id, and if it’s not 0 (i.e. root), it raises
-Program_Error. Note that if you re running the code in a container, this may
-not be sufficient, as you may have sufficient priviledge on the container,
-but not on the host machine running the container, so check that you also
-have sufficient priviledge for running the container image.
-
-@geindex Linux
-
-@geindex GNU/Linux
-
-@node GNU/Linux Topics,Microsoft Windows Topics,Specifying a Run-Time Library,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information gnu-linux-topics}@anchor{1bb}@anchor{gnat_ugn/platform_specific_information id6}@anchor{1bc}
-@section GNU/Linux Topics
-
-
-This section describes topics that are specific to GNU/Linux platforms.
-
-@menu
-* Required Packages on GNU/Linux:: 
-* A GNU/Linux Debug Quirk:: 
-
-@end menu
-
-@node Required Packages on GNU/Linux,A GNU/Linux Debug Quirk,,GNU/Linux Topics
-@anchor{gnat_ugn/platform_specific_information id7}@anchor{1bd}@anchor{gnat_ugn/platform_specific_information required-packages-on-gnu-linux}@anchor{1be}
-@subsection Required Packages on GNU/Linux
-
-
-GNAT requires the C library developer’s package to be installed.
-The name of of that package depends on your GNU/Linux distribution:
-
-
-@itemize *
-
-@item 
-RedHat, SUSE: @code{glibc-devel};
-
-@item 
-Debian, Ubuntu: @code{libc6-dev} (normally installed by default).
-@end itemize
-
-If using the 32-bit version of GNAT on a 64-bit version of GNU/Linux,
-you’ll need the 32-bit version of the following packages:
-
-
-@itemize *
-
-@item 
-RedHat, SUSE: @code{glibc.i686}, @code{glibc-devel.i686}, @code{ncurses-libs.i686}
-
-@item 
-SUSE: @code{glibc-locale-base-32bit}
-
-@item 
-Debian, Ubuntu: @code{libc6:i386}, @code{libc6-dev:i386}, @code{lib32ncursesw5}
-@end itemize
-
-Other GNU/Linux distributions might be choosing a different name
-for those packages.
-
-@node A GNU/Linux Debug Quirk,,Required Packages on GNU/Linux,GNU/Linux Topics
-@anchor{gnat_ugn/platform_specific_information a-gnu-linux-debug-quirk}@anchor{1bf}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1c0}
-@subsection A GNU/Linux Debug Quirk
-
-
-On SuSE 15, some kernels have a defect causing issues when debugging
-programs using threads or Ada tasks. Due to the lack of documentation
-found regarding this kernel issue, we can only provide limited
-information about which kernels are impacted: kernel version 5.3.18 is
-known to be impacted, and kernels in the 5.14 range or newer are
-believed to fix this problem.
-
-The bug affects the debugging of 32-bit processes on a 64-bit system.
-Symptoms can vary: Unexpected @code{SIGABRT} signals being received by
-the program, “The futex facility returned an unexpected error code”
-error message, and inferior programs hanging indefinitely range among
-the symptoms most commonly observed.
-
-@geindex Windows
-
-@node Microsoft Windows Topics,Mac OS Topics,GNU/Linux Topics,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information id9}@anchor{1c1}@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{1c2}
-@section Microsoft Windows Topics
-
-
-This section describes topics that are specific to the Microsoft Windows
-platforms.
-
-
-@menu
-* Using GNAT on Windows:: 
-* Using a network installation of GNAT:: 
-* CONSOLE and WINDOWS subsystems:: 
-* Temporary Files:: 
-* Disabling Command Line Argument Expansion:: 
-* Windows Socket Timeouts:: 
-* Mixed-Language Programming on Windows:: 
-* Windows Specific Add-Ons:: 
-
-@end menu
-
-@node Using GNAT on Windows,Using a network installation of GNAT,,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id10}@anchor{1c3}@anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{1c4}
-@subsection Using GNAT on Windows
-
-
-One of the strengths of the GNAT technology is that its tool set
-(@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
-tools that have been provided to facilitate interoperability with Windows
-when this is required. With these tools:
-
-
-@itemize *
-
-@item 
-You can build applications using the @code{CONSOLE} or @code{WINDOWS}
-subsystems.
-
-@item 
-You can use any Dynamically Linked Library (DLL) in your Ada code (both
-relocatable and non-relocatable DLLs are supported).
-
-@item 
-You can build Ada DLLs for use in other applications. These applications
-can be written in a language other than Ada (e.g., C, C++, etc). Again both
-relocatable and non-relocatable Ada DLLs are supported.
-
-@item 
-You can include Windows resources in your Ada application.
-
-@item 
-You can use or create COM/DCOM objects.
-@end itemize
-
-Immediately below are listed all known general GNAT-for-Windows restrictions.
-Other restrictions about specific features like Windows Resources and DLLs
-are listed in separate sections below.
-
-
-@itemize *
-
-@item 
-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 @code{GetLastError} and
-@code{SetLastError} when tasking, protected record, and exception
-features are not used, but it is not guaranteed to work.
-
-@item 
-It is not possible to link against Microsoft C++ libraries except for
-import libraries. Interfacing must be done by the mean of DLLs.
-
-@item 
-It is possible to link against Microsoft C libraries. Yet the preferred
-solution is to use C/C++ compiler that comes with GNAT, since it
-doesn’t require having two different development environments and makes the
-inter-language debugging experience smoother.
-
-@item 
-When the compilation environment is located on FAT32 drives, users may
-experience recompilations of the source files that have not changed if
-Daylight Saving Time (DST) state has changed since the last time files
-were compiled. NTFS drives do not have this problem.
-
-@item 
-No components of the GNAT toolset use any entries in the Windows
-registry. The only entries that can be created are file associations and
-PATH settings, provided the user has chosen to create them at installation
-time, as well as some minimal book-keeping information needed to correctly
-uninstall or integrate different GNAT products.
-@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{1c5}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1c6}
-@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 @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
-example, if GNAT is installed in @code{\GNAT} directory of a share location
-called @code{c-drive} on a machine @code{LOKI}, the following command will
-make it available:
-
-@quotation
-
-@example
-$ path \\loki\c-drive\gnat\bin;%path%`
-@end example
-@end quotation
-
-Be aware that every compilation using the network installation results in the
-transfer of large amounts of data across the network and will likely cause
-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 console-and-windows-subsystems}@anchor{1c7}@anchor{gnat_ugn/platform_specific_information id12}@anchor{1c8}
-@subsection CONSOLE and WINDOWS subsystems
-
-
-@geindex CONSOLE Subsystem
-
-@geindex WINDOWS Subsystem
-
-@geindex -mwindows
-
-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 @code{WINDOWS} subsystem. To do so
-the @code{-mwindows} linker option must be specified.
-
-@quotation
-
-@example
-$ gnatmake winprog -largs -mwindows
-@end example
-@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{1c9}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1ca}
-@subsection Temporary Files
-
-
-@geindex Temporary files
-
-It is possible to control where temporary files gets created by setting
-the 
-@geindex TMP
-@geindex environment variable; TMP
-@code{TMP} environment variable. The file will be created:
-
-
-@itemize *
-
-@item 
-Under the directory pointed to by the 
-@geindex TMP
-@geindex environment variable; TMP
-@code{TMP} environment variable if
-this directory exists.
-
-@item 
-Under @code{c:\temp}, if the 
-@geindex TMP
-@geindex environment variable; TMP
-@code{TMP} environment variable is not
-set (or not pointing to a directory) and if this directory exists.
-
-@item 
-Under the current working directory otherwise.
-@end itemize
-
-This allows you to determine exactly where the temporary
-file will be created. This is particularly useful in networked
-environments where you may not have write access to some
-directories.
-
-@node Disabling Command Line Argument Expansion,Windows Socket Timeouts,Temporary Files,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information disabling-command-line-argument-expansion}@anchor{1cb}
-@subsection Disabling Command Line Argument Expansion
-
-
-@geindex Command Line Argument Expansion
-
-By default, an executable compiled for the Windows platform will do
-the following postprocessing on the arguments passed on the command
-line:
-
-
-@itemize *
-
-@item 
-If the argument contains the characters @code{*} and/or @code{?}, then
-file expansion will be attempted. For example, if the current directory
-contains @code{a.txt} and @code{b.txt}, then when calling:
-
-@example
-$ my_ada_program *.txt
-@end example
-
-The following arguments will effectively be passed to the main program
-(for example when using @code{Ada.Command_Line.Argument}):
-
-@example
-Ada.Command_Line.Argument (1) -> "a.txt"
-Ada.Command_Line.Argument (2) -> "b.txt"
-@end example
-
-@item 
-Filename expansion can be disabled for a given argument by using single
-quotes. Thus, calling:
-
-@example
-$ my_ada_program '*.txt'
-@end example
-
-will result in:
-
-@example
-Ada.Command_Line.Argument (1) -> "*.txt"
-@end example
-@end itemize
-
-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 Ada units:
-
-@example
-Do_Argv_Expansion : Integer := 0;
-pragma Export (C, Do_Argv_Expansion, "__gnat_do_argv_expansion");
-@end example
-
-The results of previous examples will be respectively:
-
-@example
-Ada.Command_Line.Argument (1) -> "*.txt"
-@end example
-
-and:
-
-@example
-Ada.Command_Line.Argument (1) -> "'*.txt'"
-@end example
-
-@node Windows Socket Timeouts,Mixed-Language Programming on Windows,Disabling Command Line Argument Expansion,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information windows-socket-timeouts}@anchor{1cc}
-@subsection Windows Socket Timeouts
-
-
-Microsoft Windows desktops older than @code{8.0} and Microsoft Windows Servers
-older than @code{2019} set a socket timeout 500 milliseconds longer than the value
-set by setsockopt with @code{SO_RCVTIMEO} and @code{SO_SNDTIMEO} options. The GNAT
-runtime makes a correction for the difference in the corresponding Windows
-versions. For Windows Server starting with version @code{2019}, the user must
-provide a manifest file for the GNAT runtime to be able to recognize that
-the Windows version does not need the timeout correction. The manifest file
-should be located in the same directory as the executable file, and its file
-name must match the executable name suffixed by @code{.manifest}. For example,
-if the executable name is @code{sock_wto.exe}, then the manifest file name
-has to be @code{sock_wto.exe.manifest}. The manifest file must contain at
-least the following data:
-
-@example
-<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
-<compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
-<application>
-   <!-- Windows Vista -->
-   <supportedOS Id="@{e2011457-1546-43c5-a5fe-008deee3d3f0@}"/>
-   <!-- Windows 7 -->
-   <supportedOS Id="@{35138b9a-5d96-4fbd-8e2d-a2440225f93a@}"/>
-   <!-- Windows 8 -->
-   <supportedOS Id="@{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38@}"/>
-   <!-- Windows 8.1 -->
-   <supportedOS Id="@{1f676c76-80e1-4239-95bb-83d0f6d0da78@}"/>
-   <!-- Windows 10 -->
-   <supportedOS Id="@{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a@}"/>
-</application>
-</compatibility>
-</assembly>
-@end example
-
-Without the manifest file, the socket timeout is going to be overcorrected on
-these Windows Server versions and the actual time is going to be 500
-milliseconds shorter than what was set with GNAT.Sockets.Set_Socket_Option.
-Note that on Microsoft Windows versions where correction is necessary, there
-is no way to set a socket timeout shorter than 500 ms. If a socket timeout
-shorter than 500 ms is needed on these Windows versions, a call to
-Check_Selector should be added before any socket read or write operations.
-
-@node Mixed-Language Programming on Windows,Windows Specific Add-Ons,Windows Socket Timeouts,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id14}@anchor{1cd}@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{1ce}
-@subsection Mixed-Language Programming on Windows
-
-
-Developing pure Ada applications on Windows is no different than on
-other GNAT-supported platforms. However, when developing or porting an
-application that contains a mix of Ada and C/C++, the choice of your
-Windows C/C++ development environment conditions your overall
-interoperability strategy.
-
-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:
-
-
-@itemize *
-
-@item 
-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{1cf,,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{1d0,,Building DLLs with GNAT Project files}) and use the Microsoft
-or whatever environment to build your executable.
-@end itemize
-
-In addition to the description about C main in
-@ref{2c,,Mixed Language Programming} section, if the C main uses a
-stand-alone library it is required on x86-windows to
-setup the SEH context. For this the C main must looks like this:
-
-@quotation
-
-@example
-/* main.c */
-extern void adainit (void);
-extern void adafinal (void);
-extern void __gnat_initialize(void*);
-extern void call_to_ada (void);
-
-int main (int argc, char *argv[])
-@{
-  int SEH [2];
-
-  /* Initialize the SEH context */
-  __gnat_initialize (&SEH);
-
-  adainit();
-
-  /* Then call Ada services in the stand-alone library */
-
-  call_to_ada();
-
-  adafinal();
-@}
-@end example
-@end quotation
-
-Note that this is not needed on x86_64-windows where the Windows
-native SEH support is used.
-
-@menu
-* Windows Calling Conventions:: 
-* Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs. 
-* Using DLLs with GNAT:: 
-* Building DLLs with GNAT Project files:: 
-* Building DLLs with GNAT:: 
-* Building DLLs with gnatdll:: 
-* Ada DLLs and Finalization:: 
-* Creating a Spec for Ada DLLs:: 
-* GNAT and Windows Resources:: 
-* Using GNAT DLLs from Microsoft Visual Studio Applications:: 
-* Debugging a DLL:: 
-* Setting Stack Size from gnatlink:: 
-* Setting Heap Size from gnatlink:: 
-
-@end menu
-
-@node Windows Calling Conventions,Introduction to Dynamic Link Libraries DLLs,,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id15}@anchor{1d1}@anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{1d2}
-@subsubsection Windows Calling Conventions
-
-
-@geindex Stdcall
-
-@geindex APIENTRY
-
-This section pertain only to Win32. On Win64 there is a single native
-calling convention. All convention specifiers are ignored on this
-platform.
-
-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 @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 
-@code{C} (Microsoft defined)
-
-@item 
-@code{Stdcall} (Microsoft defined)
-
-@item 
-@code{Win32} (GNAT specific)
-
-@item 
-@code{DLL} (GNAT specific)
-@end itemize
-
-@menu
-* C Calling Convention:: 
-* Stdcall Calling Convention:: 
-* Win32 Calling Convention:: 
-* DLL Calling Convention:: 
-
-@end menu
-
-@node C Calling Convention,Stdcall Calling Convention,,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{1d3}@anchor{gnat_ugn/platform_specific_information id16}@anchor{1d4}
-@subsubsection @code{C} Calling Convention
-
-
-This is the default calling convention used when interfacing to C/C++
-routines compiled with either @code{gcc} or Microsoft Visual C++.
-
-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 @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 @code{C} calling convention is the name of the routine. For
-instance the C function:
-
-@quotation
-
-@example
-int get_val (long);
-@end example
-@end quotation
-
-should be imported from Ada as follows:
-
-@quotation
-
-@example
-function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
-pragma Import (C, Get_Val, External_Name => "get_val");
-@end example
-@end quotation
-
-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 @code{Link_Name} parameter
-is missing, as in the above example, this parameter is set to be the
-@code{External_Name} with a leading underscore.
-
-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 @code{Stdcall} calling
-convention, @ref{1d5,,Stdcall Calling Convention}).
-
-@node Stdcall Calling Convention,Win32 Calling Convention,C Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information id17}@anchor{1d6}@anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{1d5}
-@subsubsection @code{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 @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 @code{Stdcall} calling convention is mangled by
-adding a leading underscore (as for the @code{C} calling convention) and a
-trailing @code{@@@var{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
-@code{Stdcall} calling convention is the name of the C routine. The leading
-underscore and trailing @code{@@@var{nn}} are added automatically by
-the compiler. For instance the Win32 function:
-
-@quotation
-
-@example
-APIENTRY int get_val (long);
-@end example
-@end quotation
-
-should be imported from Ada as follows:
-
-@quotation
-
-@example
-function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
-pragma Import (Stdcall, Get_Val);
---  On the x86 a long is 4 bytes, so the Link_Name is "_get_val@@4"
-@end example
-@end quotation
-
-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:
-
-@quotation
-
-@example
-function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
-pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val");
-@end example
-@end quotation
-
-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
-
-@example
-function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
-pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val");
-@end example
-@end quotation
-
-then the imported routine is @code{retrieve_val}, that is, there is no
-decoration at all. No leading underscore and no Stdcall suffix
-@code{@@@var{nn}}.
-
-This is especially important as in some special cases a DLL’s entry
-point name lacks a trailing @code{@@@var{nn}} while the exported
-name generated for a call has it.
-
-It is also possible to import variables defined in a DLL by using an
-import pragma for a variable. As an example, if a DLL contains a
-variable defined as:
-
-@quotation
-
-@example
-int my_var;
-@end example
-@end quotation
-
-then, to access this variable from Ada you should write:
-
-@quotation
-
-@example
-My_Var : Interfaces.C.int;
-pragma Import (Stdcall, My_Var);
-@end example
-@end quotation
-
-Note that to ease building cross-platform bindings this convention
-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{1d7}@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{1d8}
-@subsubsection @code{Win32} Calling Convention
-
-
-This convention, which is GNAT-specific is fully equivalent to the
-@code{Stdcall} calling convention described above.
-
-@node DLL Calling Convention,,Win32 Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{1d9}@anchor{gnat_ugn/platform_specific_information id19}@anchor{1da}
-@subsubsection @code{DLL} Calling Convention
-
-
-This convention, which is GNAT-specific is fully equivalent to the
-@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{1db}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1dc}
-@subsubsection Introduction to Dynamic Link Libraries (DLLs)
-
-
-@geindex DLL
-
-A Dynamically Linked Library (DLL) is a library that can be shared by
-several applications running under Windows. A DLL can contain any number of
-routines and variables.
-
-One advantage of DLLs is that you can change and enhance them without
-forcing all the applications that depend on them to be relinked or
-recompiled. However, you should be aware than all calls to DLL routines are
-slower since, as you will understand below, such calls are indirect.
-
-To illustrate the remainder of this section, suppose that an application
-wants to use the services of a DLL @code{API.dll}. To use the services
-provided by @code{API.dll} you must statically link against the DLL or
-an import library which contains a jump table with an entry for each
-routine and variable exported by the DLL. In the Microsoft world this
-import library is called @code{API.lib}. When using GNAT this import
-library is called either @code{libAPI.dll.a}, @code{libapi.dll.a},
-@code{libAPI.a} or @code{libapi.a} (names are case insensitive).
-
-After you have linked your application with the DLL or the import library
-and you run your application, here is what happens:
-
-
-@itemize *
-
-@item 
-Your application is loaded into memory.
-
-@item 
-The DLL @code{API.dll} is mapped into the address space of your
-application. This means that:
-
-
-@itemize -
-
-@item 
-The DLL will use the stack of the calling thread.
-
-@item 
-The DLL will use the virtual address space of the calling process.
-
-@item 
-The DLL will allocate memory from the virtual address space of the calling
-process.
-
-@item 
-Handles (pointers) can be safely exchanged between routines in the DLL
-routines and routines in the application using the DLL.
-@end itemize
-
-@item 
-The entries in the jump table (from the import library @code{libAPI.dll.a}
-or @code{API.lib} or automatically created when linking against a DLL)
-which is part of your application are initialized with the addresses
-of the routines and variables in @code{API.dll}.
-
-@item 
-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
-
-There is an additional point which is worth mentioning. In the Windows
-world there are two kind of DLLs: relocatable and non-relocatable
-DLLs. Non-relocatable DLLs can only be loaded at a very specific address
-in the target application address space. If the addresses of two
-non-relocatable DLLs overlap and these happen to be used by the same
-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 @code{-s} linker option (see GNU Linker
-User’s Guide) removes the debugging symbols from the DLL but the DLL can
-still be relocated.
-
-As a side note, an interesting difference between Microsoft DLLs and
-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{1dd,,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{1de}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1cf}
-@subsubsection Using DLLs with GNAT
-
-
-To use the services of a DLL, say @code{API.dll}, in your Ada application
-you must have:
-
-
-@itemize *
-
-@item 
-The Ada spec for the routines and/or variables you want to access in
-@code{API.dll}. If not available this Ada spec must be built from the C/C++
-header files provided with the DLL.
-
-@item 
-The import library (@code{libAPI.dll.a} or @code{API.lib}). As previously
-mentioned an import library is a statically linked library containing the
-import table which will be filled at load time to point to the actual
-@code{API.dll} routines. Sometimes you don’t have an import library for the
-DLL you want to use. The following sections will explain how to build
-one. Note that this is optional.
-
-@item 
-The actual DLL, @code{API.dll}.
-@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 @code{My_Ada_App},
-you simply issue the command
-
-@quotation
-
-@example
-$ gnatmake my_ada_app -largs -lAPI
-@end example
-@end quotation
-
-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:
-
-
-@itemize *
-
-@item 
-@code{libAPI.dll.a}
-
-@item 
-@code{API.dll.a}
-
-@item 
-@code{libAPI.a}
-
-@item 
-@code{API.lib}
-
-@item 
-@code{libAPI.dll}
-
-@item 
-@code{API.dll}
-@end itemize
-
-The first three are the GNU style import libraries. The third is the
-Microsoft style import libraries. The last two are the actual DLL names.
-
-Note that if the Ada package spec for @code{API.dll} contains the
-following pragma
-
-@quotation
-
-@example
-pragma Linker_Options ("-lAPI");
-@end example
-@end quotation
-
-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
-example a fictitious DLL called @code{API.dll}.
-
-@menu
-* Creating an Ada Spec for the DLL Services:: 
-* Creating an Import Library:: 
-
-@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{1df}@anchor{gnat_ugn/platform_specific_information id22}@anchor{1e0}
-@subsubsection Creating an Ada Spec for the DLL Services
-
-
-A DLL typically comes with a C/C++ header file which provides the
-definitions of the routines and variables exported by the DLL. The Ada
-equivalent of this header file is a package spec that contains definitions
-for the imported entities. If the DLL you intend to use does not come with
-an Ada spec you have to generate one such spec yourself. For example if
-the header file of @code{API.dll} is a file @code{api.h} containing the
-following two definitions:
-
-@quotation
-
-@example
-int some_var;
-int get (char *);
-@end example
-@end quotation
-
-then the equivalent Ada spec could be:
-
-@quotation
-
-@example
-with Interfaces.C.Strings;
-package API is
-   use Interfaces;
-
-   Some_Var : C.int;
-   function Get (Str : C.Strings.Chars_Ptr) return C.int;
-
-private
-   pragma Import (C, Get);
-   pragma Import (DLL, Some_Var);
-end API;
-@end example
-@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 creating-an-import-library}@anchor{1e1}@anchor{gnat_ugn/platform_specific_information id23}@anchor{1e2}
-@subsubsection Creating an Import Library
-
-
-@geindex Import library
-
-If a Microsoft-style import library @code{API.lib} or a GNAT-style
-import library @code{libAPI.dll.a} or @code{libAPI.a} is available
-with @code{API.dll} you can skip this section. You can also skip this
-section if @code{API.dll} or @code{libAPI.dll} is built with GNU tools
-as in this case it is possible to link directly against the
-DLL. Otherwise read on.
-
-@geindex Definition file
-@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1dd}
-@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 @code{.def}
-suffix) has the following structure:
-
-@quotation
-
-@example
-[LIBRARY `@w{`}name`@w{`}]
-[DESCRIPTION `@w{`}string`@w{`}]
-EXPORTS
-   `@w{`}symbol1`@w{`}
-   `@w{`}symbol2`@w{`}
-   ...
-@end example
-@end quotation
-
-
-@table @asis
-
-@item `LIBRARY name'
-
-This section, which is optional, gives the name of the DLL.
-
-@item `DESCRIPTION string'
-
-This section, which is optional, gives a description string that will be
-embedded in the import library.
-
-@item `EXPORTS'
-
-This section gives the list of exported symbols (procedures, functions or
-variables). For instance in the case of @code{API.dll} the @code{EXPORTS}
-section of @code{API.def} looks like:
-
-@example
-EXPORTS
-   some_var
-   get
-@end example
-@end table
-
-Note that you must specify the correct suffix (@code{@@@var{nn}})
-(see @ref{1d2,,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{1e3}
-@subsubheading Creating a Definition File Automatically
-
-
-You can automatically create the definition file @code{API.def}
-(see @ref{1dd,,The Definition File}) from a DLL.
-For that use the @code{dlltool} program as follows:
-
-@quotation
-
-@example
-$ dlltool API.dll -z API.def --export-all-symbols
-@end example
-
-Note that if some routines in the DLL have the @code{Stdcall} convention
-(@ref{1d2,,Windows Calling Conventions}) with stripped @code{@@@var{nn}}
-suffix then you’ll have to edit @code{api.def} to add it, and specify
-@code{-k} to @code{gnatdll} when creating the import library.
-
-Here are some hints to find the right @code{@@@var{nn}} suffix.
-
-
-@itemize -
-
-@item 
-If you have the Microsoft import library (.lib), it is possible to get
-the right symbols by using Microsoft @code{dumpbin} tool (see the
-corresponding Microsoft documentation for further details).
-
-@example
-$ dumpbin /exports api.lib
-@end example
-
-@item 
-If you have a message about a missing symbol at link time the compiler
-tells you what symbol is expected. You just have to go back to the
-definition file and add the right suffix.
-@end itemize
-@end quotation
-@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{1e4}
-@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 @code{gnatdll} tool
-(see @ref{1e5,,Using gnatdll}) as follows:
-
-@quotation
-
-@example
-$ gnatdll -e API.def -d API.dll
-@end example
-
-@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 @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{1e5,,Using gnatdll} for more information about @code{gnatdll}).
-@end quotation
-@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{1e6}
-@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{1ce,,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 @code{lib} utility:
-
-@quotation
-
-@example
-$ lib -machine:IX86 -def:API.def -out:API.lib
-@end example
-
-If you use the above command the definition file @code{API.def} must
-contain a line giving the name of the DLL:
-
-@example
-LIBRARY      "API"
-@end example
-
-See the Microsoft documentation for further details about the usage of
-@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 building-dlls-with-gnat-project-files}@anchor{1d0}@anchor{gnat_ugn/platform_specific_information id24}@anchor{1e7}
-@subsubsection Building DLLs with GNAT Project files
-
-
-@geindex DLLs
-@geindex building
-
-There is nothing specific to Windows in the build process.
-See the `Library Projects' section in the `GNAT Project Manager'
-chapter of the `GPRbuild User’s Guide'.
-
-Due to a system limitation, it is not possible under Windows to create threads
-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{1e8}@anchor{gnat_ugn/platform_specific_information id25}@anchor{1e9}
-@subsubsection Building DLLs with GNAT
-
-
-@geindex DLLs
-@geindex building
-
-This section explain how to build DLLs using the GNAT built-in DLL
-support. With the following procedure it is straight forward to build
-and use DLLs with GNAT.
-
-
-@itemize *
-
-@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 @code{gnatmake} tool.
-
-@item 
-Building the DLL.
-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 ...
-@end example
-
-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 @code{gcc} a definition
-file (see @ref{1dd,,The Definition File}).
-For example:
-
-@example
-$ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o ...
-@end example
-
-If you use a definition file you must export the elaboration procedures
-for every package that required one. Elaboration procedures are named
-using the package name followed by “_E”.
-
-@item 
-Preparing DLL to be used.
-For the DLL to be used by client programs the bodies must be hidden
-from it and the .ali set with read-only attribute. This is very important
-otherwise GNAT will recompile all packages and will not actually use
-the code in the DLL. For example:
-
-@example
-$ mkdir apilib
-$ copy *.ads *.ali api.dll apilib
-$ attrib +R apilib\\*.ali
-@end example
-@end itemize
-
-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 the @code{-shared} binder
-option.
-
-@quotation
-
-@example
-$ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI
-@end example
-@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{1ea}@anchor{gnat_ugn/platform_specific_information id26}@anchor{1eb}
-@subsubsection Building DLLs with gnatdll
-
-
-@geindex DLLs
-@geindex building
-
-Note that it is preferred to use GNAT Project files
-(@ref{1d0,,Building DLLs with GNAT Project files}) or the built-in GNAT
-DLL support (@ref{1e8,,Building DLLs with GNAT}) or to build DLLs.
-
-This section explains how to build DLLs containing Ada code using
-@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
-non-Ada applications are as follows:
-
-
-@itemize *
-
-@item 
-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{1ec,,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
-@code{adainit} generated by @code{gnatbind} to perform the elaboration of
-the Ada code in the DLL (@ref{1ed,,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 @code{adafinal} generated by @code{gnatbind} to perform the
-finalization of the Ada code in the DLL (@ref{1ee,,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 spec for the services exported by the Ada DLL in each
-of the programming languages to which you plan to make the DLL available.
-
-@item 
-You must provide a definition file listing the exported entities
-(@ref{1dd,,The Definition File}).
-
-@item 
-Finally you must use @code{gnatdll} to produce the DLL and the import
-library (@ref{1e5,,Using gnatdll}).
-@end itemize
-
-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 @code{-largs -s} to @code{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'.
-
-@c Limitations_When_Using_Ada_DLLs_from Ada:
-
-@menu
-* Limitations When Using Ada DLLs from Ada:: 
-* Exporting Ada Entities:: 
-* Ada DLLs and Elaboration:: 
-
-@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{1ef}
-@subsubsection Limitations When Using Ada DLLs from Ada
-
-
-When using Ada DLLs from Ada applications there is a limitation users
-should be aware of. Because on Windows the GNAT run-time is not in a DLL of
-its own, each Ada DLL includes a part of the GNAT run-time. Specifically,
-each Ada DLL includes the services of the GNAT run-time that are necessary
-to the Ada code inside the DLL. As a result, when an Ada program uses an
-Ada DLL there are two independent GNAT run-times: one in the Ada DLL and
-one in the main program.
-
-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., @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{1ec}@anchor{gnat_ugn/platform_specific_information id27}@anchor{1f0}
-@subsubsection Exporting Ada Entities
-
-
-@geindex Export table
-
-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 @code{C} or @code{Stdcall} calling conventions to avoid
-any Ada name mangling. As an example here is an Ada package
-@code{API}, spec and body, exporting two procedures, a function, and a
-variable:
-
-@quotation
-
-@example
-with Interfaces.C; use Interfaces;
-package API is
-   Count : C.int := 0;
-   function Factorial (Val : C.int) return C.int;
-
-   procedure Initialize_API;
-   procedure Finalize_API;
-   --  Initialization & Finalization routines. More in the next section.
-private
-   pragma Export (C, Initialize_API);
-   pragma Export (C, Finalize_API);
-   pragma Export (C, Count);
-   pragma Export (C, Factorial);
-end API;
-@end example
-
-@example
-package body API is
-   function Factorial (Val : C.int) return C.int is
-      Fact : C.int := 1;
-   begin
-      Count := Count + 1;
-      for K in 1 .. Val loop
-         Fact := Fact * K;
-      end loop;
-      return Fact;
-   end Factorial;
-
-   procedure Initialize_API is
-      procedure Adainit;
-      pragma Import (C, Adainit);
-   begin
-      Adainit;
-   end Initialize_API;
-
-   procedure Finalize_API is
-      procedure Adafinal;
-      pragma Import (C, Adafinal);
-   begin
-      Adafinal;
-   end Finalize_API;
-end API;
-@end example
-@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 @code{C} or @code{Stdcall}
-convention. As an example, the previous package could be written as
-follows:
-
-@quotation
-
-@example
-package API is
-   Count : Integer := 0;
-   function Factorial (Val : Integer) return Integer;
-
-   procedure Initialize_API;
-   procedure Finalize_API;
-   --  Initialization and Finalization routines.
-end API;
-@end example
-
-@example
-package body API is
-   function Factorial (Val : Integer) return Integer is
-      Fact : Integer := 1;
-   begin
-      Count := Count + 1;
-      for K in 1 .. Val loop
-         Fact := Fact * K;
-      end loop;
-      return Fact;
-   end Factorial;
-
-   ...
-   --  The remainder of this package body is unchanged.
-end API;
-@end example
-@end quotation
-
-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{1f1,,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{1ed}@anchor{gnat_ugn/platform_specific_information id28}@anchor{1f2}
-@subsubsection Ada DLLs and Elaboration
-
-
-@geindex DLLs and elaboration
-
-The DLL that you are building contains your Ada code as well as all the
-routines in the Ada library that are needed by it. The first thing a
-user of your DLL must do is elaborate the Ada code
-(@ref{f,,Elaboration Order Handling in GNAT}).
-
-To achieve this you must export an initialization routine
-(@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 @code{adainit} generated by the GNAT binder
-(@ref{a0,,Binding with Non-Ada Main Programs}). See the body of
-@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{1e5,,Using gnatdll}).
-
-When a DLL is loaded, Windows systematically invokes a routine called
-@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
-@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 ada-dlls-and-finalization}@anchor{1ee}@anchor{gnat_ugn/platform_specific_information id29}@anchor{1f3}
-@subsubsection Ada DLLs and Finalization
-
-
-@geindex DLLs and finalization
-
-When the services of an Ada DLL are no longer needed, the client code should
-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 @code{adafinal} generated by the GNAT binder
-(@ref{a0,,Binding with Non-Ada Main Programs}).
-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 @code{gnatdll} tool
-(@ref{1e5,,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 creating-a-spec-for-ada-dlls}@anchor{1f4}@anchor{gnat_ugn/platform_specific_information id30}@anchor{1f5}
-@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 @code{API.dll},
-the corresponding C header file could look like:
-
-@quotation
-
-@example
-extern int *_imp__count;
-#define count (*_imp__count)
-int factorial (int);
-@end example
-@end 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 @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 @code{Ada} or @code{C} calling convention. As an
-example consider a DLL comprising the following package @code{API}:
-
-@quotation
-
-@example
-package API is
-   Count : Integer := 0;
-   ...
-   --  Remainder of the package omitted.
-end API;
-@end example
-@end quotation
-
-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
-
-@example
-package API is
-   Count : Integer;
-   pragma Import (DLL, Count);
-end API;
-@end example
-@end quotation
-
-@menu
-* Creating the Definition File:: 
-* Using gnatdll:: 
-
-@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{1f1}@anchor{gnat_ugn/platform_specific_information id31}@anchor{1f6}
-@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 @code{API} (where all the entities are exported
-with a @code{C} calling convention) is:
-
-@quotation
-
-@example
-EXPORTS
-    count
-    factorial
-    finalize_api
-    initialize_api
-@end example
-@end quotation
-
-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:
-
-@quotation
-
-@example
-EXPORTS
-    api__count
-    api__factorial
-    api__finalize_api
-    api__initialize_api
-@end example
-@end quotation
-
-@node Using gnatdll,,Creating the Definition File,Creating a Spec for Ada DLLs
-@anchor{gnat_ugn/platform_specific_information id32}@anchor{1f7}@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{1e5}
-@subsubsection Using @code{gnatdll}
-
-
-@geindex gnatdll
-
-@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.
-@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
-@code{gnatdll} command is
-
-@quotation
-
-@example
-$ gnatdll [ switches ] list-of-files [ -largs opts ]
-@end example
-@end quotation
-
-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 @code{list-of-files} is
-missing, only the static import library is generated.
-
-You may specify any of the following switches to @code{gnatdll}:
-
-@quotation
-
-@geindex -a (gnatdll)
-@end quotation
-
-
-@table @asis
-
-@item @code{-a[`address']}
-
-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 `address'}
-
-Set the relocatable DLL base address. By default the address is
-@code{0x11000000}.
-
-@geindex -bargs (gnatdll)
-
-@item @code{-bargs `opts'}
-
-Binder options. Pass @code{opts} to the binder.
-
-@geindex -d (gnatdll)
-
-@item @code{-d `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 @code{dllfile} is @code{xyz.dll}, the definition
-file used is @code{xyz.def}.
-
-@geindex -e (gnatdll)
-
-@item @code{-e `deffile'}
-
-@code{deffile} is the name of the definition file.
-
-@geindex -g (gnatdll)
-
-@item @code{-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
-@code{-g} switch if you plan on using the debugger or the symbolic
-stack traceback.
-
-@geindex -h (gnatdll)
-
-@item @code{-h}
-
-Help mode. Displays @code{gnatdll} switch usage information.
-
-@geindex -I (gnatdll)
-
-@item @code{-I`dir'}
-
-Direct @code{gnatdll} to search the @code{dir} directory for source and
-object files needed to build the DLL.
-(@ref{73,,Search Paths and the Run-Time Library (RTL)}).
-
-@geindex -k (gnatdll)
-
-@item @code{-k}
-
-Removes the @code{@@@var{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 @code{Stdcall} function in a DLL for which
-the @code{@@@var{nn}} suffix has been removed. This is the case for most
-of the Windows NT DLL for example. This option has no effect when
-@code{-n} option is specified.
-
-@geindex -l (gnatdll)
-
-@item @code{-l `file'}
-
-The list of ALI and object files used to build the DLL are listed in
-@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{-n}
-
-No Import. Do not create the import library.
-
-@geindex -q (gnatdll)
-
-@item @code{-q}
-
-Quiet mode. Do not display unnecessary messages.
-
-@geindex -v (gnatdll)
-
-@item @code{-v}
-
-Verbose mode. Display extra information.
-
-@geindex -largs (gnatdll)
-
-@item @code{-largs `opts'}
-
-Linker options. Pass @code{opts} to the linker.
-@end table
-
-@subsubheading @code{gnatdll} Example
-
-
-As an example the command to build a relocatable DLL from @code{api.adb}
-once @code{api.adb} has been compiled and @code{api.def} created is
-
-@quotation
-
-@example
-$ gnatdll -d api.dll api.ali
-@end example
-@end quotation
-
-The above command creates two files: @code{libapi.dll.a} (the import
-library) and @code{api.dll} (the actual DLL). If you want to create
-only the DLL, just type:
-
-@quotation
-
-@example
-$ gnatdll -d api.dll -n api.ali
-@end example
-@end quotation
-
-Alternatively if you want to create just the import library, type:
-
-@quotation
-
-@example
-$ gnatdll -d api.dll
-@end example
-@end quotation
-
-@subsubheading @code{gnatdll} behind the Scenes
-
-
-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 @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, @code{gnatdll} does
-the following:
-
-
-@itemize *
-
-@item 
-@code{gnatdll} builds the base file (@code{api.base}). A base file gives
-the information necessary to generate relocation information for the
-DLL.
-
-@example
-$ gnatbind -n api
-$ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base
-@end example
-
-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 
-@code{gnatdll} uses @code{dlltool} (see @ref{1f8,,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.
-
-@example
-$ dlltool --dllname api.dll --def api.def --base-file api.base \\
-          --output-exp api.exp
-@end example
-
-@item 
-@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
-$ gnatlink api -o api.jnk api.exp -mdll
-      -Wl,--base-file,api.base
-@end example
-
-@item 
-@code{gnatdll} builds the new export table using the new base file and
-generates the DLL import library @code{libAPI.dll.a}.
-
-@example
-$ dlltool --dllname api.dll --def api.def --base-file api.base \\
-          --output-exp api.exp --output-lib libAPI.a
-@end example
-
-@item 
-Finally @code{gnatdll} builds the relocatable DLL using the final export
-table.
-
-@example
-$ gnatbind -n api
-$ gnatlink api api.exp -o api.dll -mdll
-@end example
-@end itemize
-@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{1f8}
-@subsubheading Using @code{dlltool}
-
-
-@code{dlltool} is the low-level tool used by @code{gnatdll} to build
-DLLs and static import libraries. This section summarizes the most
-common @code{dlltool} switches. The form of the @code{dlltool} command
-is
-
-@quotation
-
-@example
-$ dlltool [`switches`]
-@end example
-@end quotation
-
-@code{dlltool} switches include:
-
-@geindex --base-file (dlltool)
-
-
-@table @asis
-
-@item @code{--base-file `basefile'}
-
-Read the base file @code{basefile} generated by the linker. This switch
-is used to create a relocatable DLL.
-@end table
-
-@geindex --def (dlltool)
-
-
-@table @asis
-
-@item @code{--def `deffile'}
-
-Read the definition file.
-@end table
-
-@geindex --dllname (dlltool)
-
-
-@table @asis
-
-@item @code{--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 @code{dlltool} with switch
-@code{--output-lib}.
-@end table
-
-@geindex -k (dlltool)
-
-
-@table @asis
-
-@item @code{-k}
-
-Kill @code{@@@var{nn}} from exported names
-(@ref{1d2,,Windows Calling Conventions}
-for a discussion about @code{Stdcall}-style symbols).
-@end table
-
-@geindex --help (dlltool)
-
-
-@table @asis
-
-@item @code{--help}
-
-Prints the @code{dlltool} switches with a concise description.
-@end table
-
-@geindex --output-exp (dlltool)
-
-
-@table @asis
-
-@item @code{--output-exp `exportfile'}
-
-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
-
-@geindex --output-lib (dlltool)
-
-
-@table @asis
-
-@item @code{--output-lib `libfile'}
-
-Generate a static import library @code{libfile}.
-@end table
-
-@geindex -v (dlltool)
-
-
-@table @asis
-
-@item @code{-v}
-
-Verbose mode.
-@end table
-
-@geindex --as (dlltool)
-
-
-@table @asis
-
-@item @code{--as `assembler-name'}
-
-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{1f9}@anchor{gnat_ugn/platform_specific_information id33}@anchor{1fa}
-@subsubsection GNAT and Windows Resources
-
-
-@geindex Resources
-@geindex windows
-
-Resources are an easy way to add Windows specific objects to your
-application. The objects that can be added as resources include:
-
-
-@itemize *
-
-@item 
-menus
-
-@item 
-accelerators
-
-@item 
-dialog boxes
-
-@item 
-string tables
-
-@item 
-bitmaps
-
-@item 
-cursors
-
-@item 
-icons
-
-@item 
-fonts
-
-@item 
-version information
-@end itemize
-
-For example, a version information resource can be defined as follow and
-embedded into an executable or DLL:
-
-A version information resource can be used to embed information into an
-executable or a DLL. These information can be viewed using the file properties
-from the Windows Explorer. Here is an example of a version information
-resource:
-
-@quotation
-
-@example
-1 VERSIONINFO
-FILEVERSION     1,0,0,0
-PRODUCTVERSION  1,0,0,0
-BEGIN
-  BLOCK "StringFileInfo"
-  BEGIN
-    BLOCK "080904E4"
-    BEGIN
-      VALUE "CompanyName", "My Company Name"
-      VALUE "FileDescription", "My application"
-      VALUE "FileVersion", "1.0"
-      VALUE "InternalName", "my_app"
-      VALUE "LegalCopyright", "My Name"
-      VALUE "OriginalFilename", "my_app.exe"
-      VALUE "ProductName", "My App"
-      VALUE "ProductVersion", "1.0"
-    END
-  END
-
-  BLOCK "VarFileInfo"
-  BEGIN
-    VALUE "Translation", 0x809, 1252
-  END
-END
-@end example
-@end quotation
-
-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
-section does not cover all resource objects, for a complete description see
-the corresponding Microsoft documentation.
-
-@menu
-* Building Resources:: 
-* Compiling Resources:: 
-* Using Resources:: 
-
-@end menu
-
-@node Building Resources,Compiling Resources,,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{1fb}@anchor{gnat_ugn/platform_specific_information id34}@anchor{1fc}
-@subsubsection Building Resources
-
-
-@geindex Resources
-@geindex building
-
-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 @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.
-
-It is not our objective to explain how to write a resource file. A
-complete description of the resource script language can be found in the
-Microsoft documentation.
-
-@node Compiling Resources,Using Resources,Building Resources,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{1fd}@anchor{gnat_ugn/platform_specific_information id35}@anchor{1fe}
-@subsubsection Compiling Resources
-
-
-@geindex rc
-
-@geindex windres
-
-@geindex Resources
-@geindex compiling
-
-This section describes how to build a GNAT-compatible (COFF) object file
-containing the resources. This is done using the Resource Compiler
-@code{windres} as follows:
-
-@quotation
-
-@example
-$ windres -i myres.rc -o myres.o
-@end example
-@end quotation
-
-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 @code{windres} @code{--preprocessor}
-parameter. A list of all possible options may be obtained by entering
-the command @code{windres} @code{--help}.
-
-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 @code{windres} to translate the @code{.res} file to a
-GNAT-compatible object file as follows:
-
-@quotation
-
-@example
-$ windres -i myres.res -o myres.o
-@end example
-@end quotation
-
-@node Using Resources,,Compiling Resources,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information id36}@anchor{1ff}@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{200}
-@subsubsection Using Resources
-
-
-@geindex Resources
-@geindex using
-
-To include the resource file in your program just add the
-GNAT-compatible object file for the resource(s) to the linker
-arguments. With @code{gnatmake} this is done by using the @code{-largs}
-option:
-
-@quotation
-
-@example
-$ gnatmake myprog -largs myres.o
-@end example
-@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{201}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{202}
-@subsubsection Using GNAT DLLs from Microsoft Visual Studio Applications
-
-
-@geindex Microsoft Visual Studio
-@geindex use with GNAT DLLs
-
-This section describes a common case of mixed GNAT/Microsoft Visual Studio
-application development, where the main program is developed using MSVS, and
-is linked with a DLL developed using GNAT. Such a mixed application should
-be developed following the general guidelines outlined above; below is the
-cookbook-style sequence of steps to follow:
-
-
-@enumerate 
-
-@item 
-First develop and build the GNAT shared library using a library project
-(let’s assume the project is @code{mylib.gpr}, producing the library @code{libmylib.dll}):
-@end enumerate
-
-@quotation
-
-@example
-$ gprbuild -p mylib.gpr
-@end example
-@end quotation
-
-
-@enumerate 2
-
-@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{1e3,,Creating Definition File Automatically}):
-@end enumerate
-
-@quotation
-
-@example
-$ dlltool libmylib.dll -z libmylib.def --export-all-symbols
-@end example
-@end quotation
-
-
-@enumerate 3
-
-@item 
-Make sure that MSVS command-line tools are accessible on the path.
-
-@item 
-Create the Microsoft-style import library (see @ref{1e6,,MSVS-Style Import Library}):
-@end enumerate
-
-@quotation
-
-@example
-$ lib -machine:IX86 -def:libmylib.def -out:libmylib.lib
-@end example
-@end quotation
-
-If you are using a 64-bit toolchain, the above becomes…
-
-@quotation
-
-@example
-$ lib -machine:X64 -def:libmylib.def -out:libmylib.lib
-@end example
-@end quotation
-
-
-@enumerate 5
-
-@item 
-Build the C main
-@end enumerate
-
-@quotation
-
-@example
-$ cl /O2 /MD main.c libmylib.lib
-@end example
-@end quotation
-
-
-@enumerate 6
-
-@item 
-Before running the executable, make sure you have set the PATH to the DLL,
-or copy the DLL into into the directory containing the .exe.
-@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 debugging-a-dll}@anchor{203}@anchor{gnat_ugn/platform_specific_information id37}@anchor{204}
-@subsubsection Debugging a DLL
-
-
-@geindex DLL debugging
-
-Debugging a DLL is similar to debugging a standard program. But
-we have to deal with two different executable parts: the DLL and the
-program that uses it. We have the following four possibilities:
-
-
-@itemize *
-
-@item 
-The program and the DLL are built with GCC/GNAT.
-
-@item 
-The program is built with foreign tools and the DLL is built with
-GCC/GNAT.
-
-@item 
-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 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.
-
-@menu
-* Program and DLL Both Built with GCC/GNAT:: 
-* Program Built with Foreign Tools and DLL Built with GCC/GNAT:: 
-
-@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 id38}@anchor{205}@anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{206}
-@subsubsection Program and DLL Both Built with GCC/GNAT
-
-
-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
-@code{ada_main} and that in the DLL there is an entry point named
-@code{ada_dll}.
-
-The DLL (@ref{1dc,,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 @code{GDB} on the main program.
-
-@example
-$ gdb -nw ada_main
-@end example
-
-@item 
-Start the program and stop at the beginning of the main procedure
-
-@example
-(gdb) start
-@end example
-
-This step is required to be able to set a breakpoint inside the DLL. As long
-as the program is not run, the DLL is not loaded. This has the
-consequence that the DLL debugging information is also not loaded, so it is not
-possible to set a breakpoint in the DLL.
-
-@item 
-Set a breakpoint inside the DLL
-
-@example
-(gdb) break ada_dll
-(gdb) cont
-@end example
-@end itemize
-
-At this stage a breakpoint is set inside the DLL. From there on
-you can use the standard approach to debug the whole program
-(@ref{14d,,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 id39}@anchor{207}@anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{208}
-@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 @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 @code{main} (this is for
-example some C code built with Microsoft Visual C) and that there is a
-DLL named @code{test.dll} containing an Ada entry point named
-@code{ada_dll}.
-
-The DLL (see @ref{1dc,,Introduction to Dynamic Link Libraries (DLLs)}) must have
-been built with debugging information (see the GNAT @code{-g} option).
-
-@subsubheading Debugging the DLL Directly
-
-
-
-@itemize *
-
-@item 
-Find out the executable starting address
-
-@example
-$ objdump --file-header main.exe
-@end example
-
-The starting address is reported on the last line. For example:
-
-@example
-main.exe:     file format pei-i386
-architecture: i386, flags 0x0000010a:
-EXEC_P, HAS_DEBUG, D_PAGED
-start address 0x00401010
-@end example
-
-@item 
-Launch the debugger on the executable.
-
-@example
-$ gdb main.exe
-@end example
-
-@item 
-Set a breakpoint at the starting address, and launch the program.
-
-@example
-$ (gdb) break *0x00401010
-$ (gdb) run
-@end example
-
-The program will stop at the given address.
-
-@item 
-Set a breakpoint on a DLL subroutine.
-
-@example
-(gdb) break ada_dll.adb:45
-@end example
-
-Or if you want to break using a symbol on the DLL, you need first to
-select the Ada language (language used by the DLL).
-
-@example
-(gdb) set language ada
-(gdb) break ada_dll
-@end example
-
-@item 
-Continue the program.
-
-@example
-(gdb) cont
-@end example
-
-This will run the program until it reaches the breakpoint that has been
-set. From that point you can use the standard way to debug a program
-as described in (@ref{14d,,Running and Debugging Ada Programs}).
-@end itemize
-
-It is also possible to debug the DLL by attaching to a running process.
-
-@subsubheading Attaching to a Running Process
-
-
-@geindex DLL debugging
-@geindex attach to process
-
-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
-loop in the code of the DLL to meet this criterion.
-
-
-@itemize *
-
-@item 
-Launch the main program @code{main.exe}.
-
-@example
-$ main
-@end example
-
-@item 
-Use the Windows `Task Manager' to find the process ID. Let’s say
-that the process PID for @code{main.exe} is 208.
-
-@item 
-Launch gdb.
-
-@example
-$ gdb
-@end example
-
-@item 
-Attach to the running process to be debugged.
-
-@example
-(gdb) attach 208
-@end example
-
-@item 
-Load the process debugging information.
-
-@example
-(gdb) symbol-file main.exe
-@end example
-
-@item 
-Break somewhere in the DLL.
-
-@example
-(gdb) break ada_dll
-@end example
-
-@item 
-Continue process execution.
-
-@example
-(gdb) cont
-@end example
-@end itemize
-
-This last step will resume the process execution, and stop at
-the breakpoint we have set. From there you can use the standard
-approach to debug a program as described in
-@ref{14d,,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 id40}@anchor{209}@anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{127}
-@subsubsection Setting Stack Size from @code{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
-the main stack (environment task). The other task stacks are set with pragma
-Storage_Size or with the `gnatbind -d' command.
-
-Since older versions of Windows (2000, NT4, etc.) do not allow setting the
-reserve size of individual tasks, the link-time stack size applies to all
-tasks, and pragma Storage_Size has no effect.
-In particular, Stack Overflow checks are made against this
-link-time specified size.
-
-This setting can be done with @code{gnatlink} using either of the following:
-
-
-@itemize *
-
-@item 
-@code{-Xlinker} linker option
-
-@example
-$ gnatlink hello -Xlinker --stack=0x10000,0x1000
-@end example
-
-This sets the stack reserve size to 0x10000 bytes and the stack commit
-size to 0x1000 bytes.
-
-@item 
-@code{-Wl} linker option
-
-@example
-$ gnatlink hello -Wl,--stack=0x1000000
-@end example
-
-This sets the stack reserve size to 0x1000000 bytes. Note that with
-@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 id41}@anchor{20a}@anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{128}
-@subsubsection Setting Heap Size from @code{gnatlink}
-
-
-Under Windows systems, it is possible to specify the program heap size from
-@code{gnatlink} using either of the following:
-
-
-@itemize *
-
-@item 
-@code{-Xlinker} linker option
-
-@example
-$ gnatlink hello -Xlinker --heap=0x10000,0x1000
-@end example
-
-This sets the heap reserve size to 0x10000 bytes and the heap commit
-size to 0x1000 bytes.
-
-@item 
-@code{-Wl} linker option
-
-@example
-$ gnatlink hello -Wl,--heap=0x1000000
-@end example
-
-This sets the heap reserve size to 0x1000000 bytes. Note that with
-@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 win32-specific-addons}@anchor{20b}@anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{20c}
-@subsection Windows Specific Add-Ons
-
-
-This section describes the Windows specific add-ons.
-
-@menu
-* Win32Ada:: 
-* wPOSIX:: 
-
-@end menu
-
-@node Win32Ada,wPOSIX,,Windows Specific Add-Ons
-@anchor{gnat_ugn/platform_specific_information id42}@anchor{20d}@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{20e}
-@subsubsection Win32Ada
-
-
-Win32Ada is a binding for the Microsoft Win32 API. This binding can be
-easily installed from the provided installer. To use the Win32Ada
-binding you need to use a project file, and adding a single with_clause
-will give you full access to the Win32Ada binding sources and ensure
-that the proper libraries are passed to the linker.
-
-@quotation
-
-@example
-with "win32ada";
-project P is
-   for Sources use ...;
-end P;
-@end example
-@end quotation
-
-To build the application you just need to call gprbuild for the
-application’s project, here p.gpr:
-
-@quotation
-
-@example
-gprbuild p.gpr
-@end example
-@end quotation
-
-@node wPOSIX,,Win32Ada,Windows Specific Add-Ons
-@anchor{gnat_ugn/platform_specific_information id43}@anchor{20f}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{210}
-@subsubsection wPOSIX
-
-
-wPOSIX is a minimal POSIX binding whose goal is to help with building
-cross-platforms applications. This binding is not complete though, as
-the Win32 API does not provide the necessary support for all POSIX APIs.
-
-To use the wPOSIX binding you need to use a project file, and adding
-a single with_clause will give you full access to the wPOSIX binding
-sources and ensure that the proper libraries are passed to the linker.
-
-@quotation
-
-@example
-with "wposix";
-project P is
-   for Sources use ...;
-end P;
-@end example
-@end quotation
-
-To build the application you just need to call gprbuild for the
-application’s project, here p.gpr:
-
-@quotation
-
-@example
-gprbuild p.gpr
-@end example
-@end quotation
-
-@node Mac OS Topics,,Microsoft Windows Topics,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information id44}@anchor{211}@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{212}
-@section Mac OS Topics
-
-
-@geindex OS X
-
-This section describes topics that are specific to Apple’s OS X
-platform.
-
-@menu
-* Codesigning the Debugger:: 
-
-@end menu
-
-@node Codesigning the Debugger,,,Mac OS Topics
-@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{213}
-@subsection Codesigning the Debugger
-
-
-The Darwin Kernel requires the debugger to have special permissions
-before it is allowed to control other processes. These permissions
-are granted by codesigning the GDB executable. Without these
-permissions, the debugger will report error messages such as:
-
-@example
-Starting program: /x/y/foo
-Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5).
-(please check gdb is codesigned - see taskgated(8))
-@end example
-
-Codesigning requires a certificate.  The following procedure explains
-how to create one:
-
-
-@itemize *
-
-@item 
-Start the Keychain Access application (in
-/Applications/Utilities/Keychain Access.app)
-
-@item 
-Select the Keychain Access -> Certificate Assistant ->
-Create a Certificate… menu
-
-@item 
-Then:
-
-
-@itemize *
-
-@item 
-Choose a name for the new certificate (this procedure will use
-“gdb-cert” as an example)
-
-@item 
-Set “Identity Type” to “Self Signed Root”
-
-@item 
-Set “Certificate Type” to “Code Signing”
-
-@item 
-Activate the “Let me override defaults” option
-@end itemize
-
-@item 
-Click several times on “Continue” until the “Specify a Location
-For The Certificate” screen appears, then set “Keychain” to “System”
-
-@item 
-Click on “Continue” until the certificate is created
-
-@item 
-Finally, in the view, double-click on the new certificate,
-and set “When using this certificate” to “Always Trust”
-
-@item 
-Exit the Keychain Access application and restart the computer
-(this is unfortunately required)
-@end itemize
-
-Once a certificate has been created, the debugger can be codesigned
-as follow. In a Terminal, run the following command:
-
-@quotation
-
-@example
-$ codesign -f -s  "gdb-cert"  <gnat_install_prefix>/bin/gdb
-@end example
-@end quotation
-
-where “gdb-cert” should be replaced by the actual certificate
-name chosen above, and <gnat_install_prefix> should be replaced by
-the location where you installed GNAT.  Also, be sure that users are
-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 doc}@anchor{214}@anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{e}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{215}
-@chapter Example of Binder Output File
-
-
-@geindex Binder output (example)
-
-This Appendix displays the source code for the output file
-generated by `gnatbind' for a simple ‘Hello World’ program.
-Comments have been added for clarification purposes.
-
-@example
---  The package is called Ada_Main unless this name is actually used
---  as a unit name in the partition, in which case some other unique
---  name is used.
-
-pragma Ada_95;
-with System;
-package ada_main is
-   pragma Warnings (Off);
-
-   --  The main program saves the parameters (argument count,
-   --  argument values, environment pointer) in global variables
-   --  for later access by other units including
-   --  Ada.Command_Line.
-
-   gnat_argc : Integer;
-   gnat_argv : System.Address;
-   gnat_envp : System.Address;
-
-   --  The actual variables are stored in a library routine. This
-   --  is useful for some shared library situations, where there
-   --  are problems if variables are not in the library.
-
-   pragma Import (C, gnat_argc);
-   pragma Import (C, gnat_argv);
-   pragma Import (C, gnat_envp);
-
-   --  The exit status is similarly an external location
-
-   gnat_exit_status : Integer;
-   pragma Import (C, gnat_exit_status);
-
-   GNAT_Version : constant String :=
-                    "GNAT Version: Pro 7.4.0w (20141119-49)" & ASCII.NUL;
-   pragma Export (C, GNAT_Version, "__gnat_version");
-
-   Ada_Main_Program_Name : constant String := "_ada_hello" & ASCII.NUL;
-   pragma Export (C, Ada_Main_Program_Name, "__gnat_ada_main_program_name");
-
-   --  This is the generated adainit routine that performs
-   --  initialization at the start of execution. In the case
-   --  where Ada is the main program, this main program makes
-   --  a call to adainit at program startup.
-
-   procedure adainit;
-   pragma Export (C, adainit, "adainit");
-
-   --  This is the generated adafinal routine that performs
-   --  finalization at the end of execution. In the case where
-   --  Ada is the main program, this main program makes a call
-   --  to adafinal at program termination.
-
-   procedure adafinal;
-   pragma Export (C, adafinal, "adafinal");
-
-   --  This routine is called at the start of execution. It is
-   --  a dummy routine that is used by the debugger to breakpoint
-   --  at the start of execution.
-
-   --  This is the actual generated main program (it would be
-   --  suppressed if the no main program switch were used). As
-   --  required by standard system conventions, this program has
-   --  the external name main.
-
-   function main
-     (argc : Integer;
-      argv : System.Address;
-      envp : System.Address)
-      return Integer;
-   pragma Export (C, main, "main");
-
-   --  The following set of constants give the version
-   --  identification values for every unit in the bound
-   --  partition. This identification is computed from all
-   --  dependent semantic units, and corresponds to the
-   --  string that would be returned by use of the
-   --  Body_Version or Version attributes.
-
-   --  The following Export pragmas export the version numbers
-   --  with symbolic names ending in B (for body) or S
-   --  (for spec) so that they can be located in a link. The
-   --  information provided here is sufficient to track down
-   --  the exact versions of units used in a given build.
-
-   type Version_32 is mod 2 ** 32;
-   u00001 : constant Version_32 := 16#8ad6e54a#;
-   pragma Export (C, u00001, "helloB");
-   u00002 : constant Version_32 := 16#fbff4c67#;
-   pragma Export (C, u00002, "system__standard_libraryB");
-   u00003 : constant Version_32 := 16#1ec6fd90#;
-   pragma Export (C, u00003, "system__standard_libraryS");
-   u00004 : constant Version_32 := 16#3ffc8e18#;
-   pragma Export (C, u00004, "adaS");
-   u00005 : constant Version_32 := 16#28f088c2#;
-   pragma Export (C, u00005, "ada__text_ioB");
-   u00006 : constant Version_32 := 16#f372c8ac#;
-   pragma Export (C, u00006, "ada__text_ioS");
-   u00007 : constant Version_32 := 16#2c143749#;
-   pragma Export (C, u00007, "ada__exceptionsB");
-   u00008 : constant Version_32 := 16#f4f0cce8#;
-   pragma Export (C, u00008, "ada__exceptionsS");
-   u00009 : constant Version_32 := 16#a46739c0#;
-   pragma Export (C, u00009, "ada__exceptions__last_chance_handlerB");
-   u00010 : constant Version_32 := 16#3aac8c92#;
-   pragma Export (C, u00010, "ada__exceptions__last_chance_handlerS");
-   u00011 : constant Version_32 := 16#1d274481#;
-   pragma Export (C, u00011, "systemS");
-   u00012 : constant Version_32 := 16#a207fefe#;
-   pragma Export (C, u00012, "system__soft_linksB");
-   u00013 : constant Version_32 := 16#467d9556#;
-   pragma Export (C, u00013, "system__soft_linksS");
-   u00014 : constant Version_32 := 16#b01dad17#;
-   pragma Export (C, u00014, "system__parametersB");
-   u00015 : constant Version_32 := 16#630d49fe#;
-   pragma Export (C, u00015, "system__parametersS");
-   u00016 : constant Version_32 := 16#b19b6653#;
-   pragma Export (C, u00016, "system__secondary_stackB");
-   u00017 : constant Version_32 := 16#b6468be8#;
-   pragma Export (C, u00017, "system__secondary_stackS");
-   u00018 : constant Version_32 := 16#39a03df9#;
-   pragma Export (C, u00018, "system__storage_elementsB");
-   u00019 : constant Version_32 := 16#30e40e85#;
-   pragma Export (C, u00019, "system__storage_elementsS");
-   u00020 : constant Version_32 := 16#41837d1e#;
-   pragma Export (C, u00020, "system__stack_checkingB");
-   u00021 : constant Version_32 := 16#93982f69#;
-   pragma Export (C, u00021, "system__stack_checkingS");
-   u00022 : constant Version_32 := 16#393398c1#;
-   pragma Export (C, u00022, "system__exception_tableB");
-   u00023 : constant Version_32 := 16#b33e2294#;
-   pragma Export (C, u00023, "system__exception_tableS");
-   u00024 : constant Version_32 := 16#ce4af020#;
-   pragma Export (C, u00024, "system__exceptionsB");
-   u00025 : constant Version_32 := 16#75442977#;
-   pragma Export (C, u00025, "system__exceptionsS");
-   u00026 : constant Version_32 := 16#37d758f1#;
-   pragma Export (C, u00026, "system__exceptions__machineS");
-   u00027 : constant Version_32 := 16#b895431d#;
-   pragma Export (C, u00027, "system__exceptions_debugB");
-   u00028 : constant Version_32 := 16#aec55d3f#;
-   pragma Export (C, u00028, "system__exceptions_debugS");
-   u00029 : constant Version_32 := 16#570325c8#;
-   pragma Export (C, u00029, "system__img_intB");
-   u00030 : constant Version_32 := 16#1ffca443#;
-   pragma Export (C, u00030, "system__img_intS");
-   u00031 : constant Version_32 := 16#b98c3e16#;
-   pragma Export (C, u00031, "system__tracebackB");
-   u00032 : constant Version_32 := 16#831a9d5a#;
-   pragma Export (C, u00032, "system__tracebackS");
-   u00033 : constant Version_32 := 16#9ed49525#;
-   pragma Export (C, u00033, "system__traceback_entriesB");
-   u00034 : constant Version_32 := 16#1d7cb2f1#;
-   pragma Export (C, u00034, "system__traceback_entriesS");
-   u00035 : constant Version_32 := 16#8c33a517#;
-   pragma Export (C, u00035, "system__wch_conB");
-   u00036 : constant Version_32 := 16#065a6653#;
-   pragma Export (C, u00036, "system__wch_conS");
-   u00037 : constant Version_32 := 16#9721e840#;
-   pragma Export (C, u00037, "system__wch_stwB");
-   u00038 : constant Version_32 := 16#2b4b4a52#;
-   pragma Export (C, u00038, "system__wch_stwS");
-   u00039 : constant Version_32 := 16#92b797cb#;
-   pragma Export (C, u00039, "system__wch_cnvB");
-   u00040 : constant Version_32 := 16#09eddca0#;
-   pragma Export (C, u00040, "system__wch_cnvS");
-   u00041 : constant Version_32 := 16#6033a23f#;
-   pragma Export (C, u00041, "interfacesS");
-   u00042 : constant Version_32 := 16#ece6fdb6#;
-   pragma Export (C, u00042, "system__wch_jisB");
-   u00043 : constant Version_32 := 16#899dc581#;
-   pragma Export (C, u00043, "system__wch_jisS");
-   u00044 : constant Version_32 := 16#10558b11#;
-   pragma Export (C, u00044, "ada__streamsB");
-   u00045 : constant Version_32 := 16#2e6701ab#;
-   pragma Export (C, u00045, "ada__streamsS");
-   u00046 : constant Version_32 := 16#db5c917c#;
-   pragma Export (C, u00046, "ada__io_exceptionsS");
-   u00047 : constant Version_32 := 16#12c8cd7d#;
-   pragma Export (C, u00047, "ada__tagsB");
-   u00048 : constant Version_32 := 16#ce72c228#;
-   pragma Export (C, u00048, "ada__tagsS");
-   u00049 : constant Version_32 := 16#c3335bfd#;
-   pragma Export (C, u00049, "system__htableB");
-   u00050 : constant Version_32 := 16#99e5f76b#;
-   pragma Export (C, u00050, "system__htableS");
-   u00051 : constant Version_32 := 16#089f5cd0#;
-   pragma Export (C, u00051, "system__string_hashB");
-   u00052 : constant Version_32 := 16#3bbb9c15#;
-   pragma Export (C, u00052, "system__string_hashS");
-   u00053 : constant Version_32 := 16#807fe041#;
-   pragma Export (C, u00053, "system__unsigned_typesS");
-   u00054 : constant Version_32 := 16#d27be59e#;
-   pragma Export (C, u00054, "system__val_lluB");
-   u00055 : constant Version_32 := 16#fa8db733#;
-   pragma Export (C, u00055, "system__val_lluS");
-   u00056 : constant Version_32 := 16#27b600b2#;
-   pragma Export (C, u00056, "system__val_utilB");
-   u00057 : constant Version_32 := 16#b187f27f#;
-   pragma Export (C, u00057, "system__val_utilS");
-   u00058 : constant Version_32 := 16#d1060688#;
-   pragma Export (C, u00058, "system__case_utilB");
-   u00059 : constant Version_32 := 16#392e2d56#;
-   pragma Export (C, u00059, "system__case_utilS");
-   u00060 : constant Version_32 := 16#84a27f0d#;
-   pragma Export (C, u00060, "interfaces__c_streamsB");
-   u00061 : constant Version_32 := 16#8bb5f2c0#;
-   pragma Export (C, u00061, "interfaces__c_streamsS");
-   u00062 : constant Version_32 := 16#6db6928f#;
-   pragma Export (C, u00062, "system__crtlS");
-   u00063 : constant Version_32 := 16#4e6a342b#;
-   pragma Export (C, u00063, "system__file_ioB");
-   u00064 : constant Version_32 := 16#ba56a5e4#;
-   pragma Export (C, u00064, "system__file_ioS");
-   u00065 : constant Version_32 := 16#b7ab275c#;
-   pragma Export (C, u00065, "ada__finalizationB");
-   u00066 : constant Version_32 := 16#19f764ca#;
-   pragma Export (C, u00066, "ada__finalizationS");
-   u00067 : constant Version_32 := 16#95817ed8#;
-   pragma Export (C, u00067, "system__finalization_rootB");
-   u00068 : constant Version_32 := 16#52d53711#;
-   pragma Export (C, u00068, "system__finalization_rootS");
-   u00069 : constant Version_32 := 16#769e25e6#;
-   pragma Export (C, u00069, "interfaces__cB");
-   u00070 : constant Version_32 := 16#4a38bedb#;
-   pragma Export (C, u00070, "interfaces__cS");
-   u00071 : constant Version_32 := 16#07e6ee66#;
-   pragma Export (C, u00071, "system__os_libB");
-   u00072 : constant Version_32 := 16#d7b69782#;
-   pragma Export (C, u00072, "system__os_libS");
-   u00073 : constant Version_32 := 16#1a817b8e#;
-   pragma Export (C, u00073, "system__stringsB");
-   u00074 : constant Version_32 := 16#639855e7#;
-   pragma Export (C, u00074, "system__stringsS");
-   u00075 : constant Version_32 := 16#e0b8de29#;
-   pragma Export (C, u00075, "system__file_control_blockS");
-   u00076 : constant Version_32 := 16#b5b2aca1#;
-   pragma Export (C, u00076, "system__finalization_mastersB");
-   u00077 : constant Version_32 := 16#69316dc1#;
-   pragma Export (C, u00077, "system__finalization_mastersS");
-   u00078 : constant Version_32 := 16#57a37a42#;
-   pragma Export (C, u00078, "system__address_imageB");
-   u00079 : constant Version_32 := 16#bccbd9bb#;
-   pragma Export (C, u00079, "system__address_imageS");
-   u00080 : constant Version_32 := 16#7268f812#;
-   pragma Export (C, u00080, "system__img_boolB");
-   u00081 : constant Version_32 := 16#e8fe356a#;
-   pragma Export (C, u00081, "system__img_boolS");
-   u00082 : constant Version_32 := 16#d7aac20c#;
-   pragma Export (C, u00082, "system__ioB");
-   u00083 : constant Version_32 := 16#8365b3ce#;
-   pragma Export (C, u00083, "system__ioS");
-   u00084 : constant Version_32 := 16#6d4d969a#;
-   pragma Export (C, u00084, "system__storage_poolsB");
-   u00085 : constant Version_32 := 16#e87cc305#;
-   pragma Export (C, u00085, "system__storage_poolsS");
-   u00086 : constant Version_32 := 16#e34550ca#;
-   pragma Export (C, u00086, "system__pool_globalB");
-   u00087 : constant Version_32 := 16#c88d2d16#;
-   pragma Export (C, u00087, "system__pool_globalS");
-   u00088 : constant Version_32 := 16#9d39c675#;
-   pragma Export (C, u00088, "system__memoryB");
-   u00089 : constant Version_32 := 16#445a22b5#;
-   pragma Export (C, u00089, "system__memoryS");
-   u00090 : constant Version_32 := 16#6a859064#;
-   pragma Export (C, u00090, "system__storage_pools__subpoolsB");
-   u00091 : constant Version_32 := 16#e3b008dc#;
-   pragma Export (C, u00091, "system__storage_pools__subpoolsS");
-   u00092 : constant Version_32 := 16#63f11652#;
-   pragma Export (C, u00092, "system__storage_pools__subpools__finalizationB");
-   u00093 : constant Version_32 := 16#fe2f4b3a#;
-   pragma Export (C, u00093, "system__storage_pools__subpools__finalizationS");
-
-   --  BEGIN ELABORATION ORDER
-   --  ada%s
-   --  interfaces%s
-   --  system%s
-   --  system.case_util%s
-   --  system.case_util%b
-   --  system.htable%s
-   --  system.img_bool%s
-   --  system.img_bool%b
-   --  system.img_int%s
-   --  system.img_int%b
-   --  system.io%s
-   --  system.io%b
-   --  system.parameters%s
-   --  system.parameters%b
-   --  system.crtl%s
-   --  interfaces.c_streams%s
-   --  interfaces.c_streams%b
-   --  system.standard_library%s
-   --  system.exceptions_debug%s
-   --  system.exceptions_debug%b
-   --  system.storage_elements%s
-   --  system.storage_elements%b
-   --  system.stack_checking%s
-   --  system.stack_checking%b
-   --  system.string_hash%s
-   --  system.string_hash%b
-   --  system.htable%b
-   --  system.strings%s
-   --  system.strings%b
-   --  system.os_lib%s
-   --  system.traceback_entries%s
-   --  system.traceback_entries%b
-   --  ada.exceptions%s
-   --  system.soft_links%s
-   --  system.unsigned_types%s
-   --  system.val_llu%s
-   --  system.val_util%s
-   --  system.val_util%b
-   --  system.val_llu%b
-   --  system.wch_con%s
-   --  system.wch_con%b
-   --  system.wch_cnv%s
-   --  system.wch_jis%s
-   --  system.wch_jis%b
-   --  system.wch_cnv%b
-   --  system.wch_stw%s
-   --  system.wch_stw%b
-   --  ada.exceptions.last_chance_handler%s
-   --  ada.exceptions.last_chance_handler%b
-   --  system.address_image%s
-   --  system.exception_table%s
-   --  system.exception_table%b
-   --  ada.io_exceptions%s
-   --  ada.tags%s
-   --  ada.streams%s
-   --  ada.streams%b
-   --  interfaces.c%s
-   --  system.exceptions%s
-   --  system.exceptions%b
-   --  system.exceptions.machine%s
-   --  system.finalization_root%s
-   --  system.finalization_root%b
-   --  ada.finalization%s
-   --  ada.finalization%b
-   --  system.storage_pools%s
-   --  system.storage_pools%b
-   --  system.finalization_masters%s
-   --  system.storage_pools.subpools%s
-   --  system.storage_pools.subpools.finalization%s
-   --  system.storage_pools.subpools.finalization%b
-   --  system.memory%s
-   --  system.memory%b
-   --  system.standard_library%b
-   --  system.pool_global%s
-   --  system.pool_global%b
-   --  system.file_control_block%s
-   --  system.file_io%s
-   --  system.secondary_stack%s
-   --  system.file_io%b
-   --  system.storage_pools.subpools%b
-   --  system.finalization_masters%b
-   --  interfaces.c%b
-   --  ada.tags%b
-   --  system.soft_links%b
-   --  system.os_lib%b
-   --  system.secondary_stack%b
-   --  system.address_image%b
-   --  system.traceback%s
-   --  ada.exceptions%b
-   --  system.traceback%b
-   --  ada.text_io%s
-   --  ada.text_io%b
-   --  hello%b
-   --  END ELABORATION ORDER
-
-end ada_main;
-@end example
-
-@example
-pragma Ada_95;
---  The following source file name pragmas allow the generated file
---  names to be unique for different main programs. They are needed
---  since the package name will always be Ada_Main.
-
-pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads");
-pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb");
-
-pragma Suppress (Overflow_Check);
-with Ada.Exceptions;
-
---  Generated package body for Ada_Main starts here
-
-package body ada_main is
-   pragma Warnings (Off);
-
-   --  These values are reference counter associated to units which have
-   --  been elaborated. It is also used to avoid elaborating the
-   --  same unit twice.
-
-   E72 : Short_Integer; pragma Import (Ada, E72, "system__os_lib_E");
-   E13 : Short_Integer; pragma Import (Ada, E13, "system__soft_links_E");
-   E23 : Short_Integer; pragma Import (Ada, E23, "system__exception_table_E");
-   E46 : Short_Integer; pragma Import (Ada, E46, "ada__io_exceptions_E");
-   E48 : Short_Integer; pragma Import (Ada, E48, "ada__tags_E");
-   E45 : Short_Integer; pragma Import (Ada, E45, "ada__streams_E");
-   E70 : Short_Integer; pragma Import (Ada, E70, "interfaces__c_E");
-   E25 : Short_Integer; pragma Import (Ada, E25, "system__exceptions_E");
-   E68 : Short_Integer; pragma Import (Ada, E68, "system__finalization_root_E");
-   E66 : Short_Integer; pragma Import (Ada, E66, "ada__finalization_E");
-   E85 : Short_Integer; pragma Import (Ada, E85, "system__storage_pools_E");
-   E77 : Short_Integer; pragma Import (Ada, E77, "system__finalization_masters_E");
-   E91 : Short_Integer; pragma Import (Ada, E91, "system__storage_pools__subpools_E");
-   E87 : Short_Integer; pragma Import (Ada, E87, "system__pool_global_E");
-   E75 : Short_Integer; pragma Import (Ada, E75, "system__file_control_block_E");
-   E64 : Short_Integer; pragma Import (Ada, E64, "system__file_io_E");
-   E17 : Short_Integer; pragma Import (Ada, E17, "system__secondary_stack_E");
-   E06 : Short_Integer; pragma Import (Ada, E06, "ada__text_io_E");
-
-   Local_Priority_Specific_Dispatching : constant String := "";
-   Local_Interrupt_States : constant String := "";
-
-   Is_Elaborated : Boolean := False;
-
-   procedure finalize_library is
-   begin
-      E06 := E06 - 1;
-      declare
-         procedure F1;
-         pragma Import (Ada, F1, "ada__text_io__finalize_spec");
-      begin
-         F1;
-      end;
-      E77 := E77 - 1;
-      E91 := E91 - 1;
-      declare
-         procedure F2;
-         pragma Import (Ada, F2, "system__file_io__finalize_body");
-      begin
-         E64 := E64 - 1;
-         F2;
-      end;
-      declare
-         procedure F3;
-         pragma Import (Ada, F3, "system__file_control_block__finalize_spec");
-      begin
-         E75 := E75 - 1;
-         F3;
-      end;
-      E87 := E87 - 1;
-      declare
-         procedure F4;
-         pragma Import (Ada, F4, "system__pool_global__finalize_spec");
-      begin
-         F4;
-      end;
-      declare
-         procedure F5;
-         pragma Import (Ada, F5, "system__storage_pools__subpools__finalize_spec");
-      begin
-         F5;
-      end;
-      declare
-         procedure F6;
-         pragma Import (Ada, F6, "system__finalization_masters__finalize_spec");
-      begin
-         F6;
-      end;
-      declare
-         procedure Reraise_Library_Exception_If_Any;
-         pragma Import (Ada, Reraise_Library_Exception_If_Any, "__gnat_reraise_library_exception_if_any");
-      begin
-         Reraise_Library_Exception_If_Any;
-      end;
-   end finalize_library;
-
-   -------------
-   -- adainit --
-   -------------
-
-   procedure adainit is
-
-      Main_Priority : Integer;
-      pragma Import (C, Main_Priority, "__gl_main_priority");
-      Time_Slice_Value : Integer;
-      pragma Import (C, Time_Slice_Value, "__gl_time_slice_val");
-      WC_Encoding : Character;
-      pragma Import (C, WC_Encoding, "__gl_wc_encoding");
-      Locking_Policy : Character;
-      pragma Import (C, Locking_Policy, "__gl_locking_policy");
-      Queuing_Policy : Character;
-      pragma Import (C, Queuing_Policy, "__gl_queuing_policy");
-      Task_Dispatching_Policy : Character;
-      pragma Import (C, Task_Dispatching_Policy, "__gl_task_dispatching_policy");
-      Priority_Specific_Dispatching : System.Address;
-      pragma Import (C, Priority_Specific_Dispatching, "__gl_priority_specific_dispatching");
-      Num_Specific_Dispatching : Integer;
-      pragma Import (C, Num_Specific_Dispatching, "__gl_num_specific_dispatching");
-      Main_CPU : Integer;
-      pragma Import (C, Main_CPU, "__gl_main_cpu");
-      Interrupt_States : System.Address;
-      pragma Import (C, Interrupt_States, "__gl_interrupt_states");
-      Num_Interrupt_States : Integer;
-      pragma Import (C, Num_Interrupt_States, "__gl_num_interrupt_states");
-      Unreserve_All_Interrupts : Integer;
-      pragma Import (C, Unreserve_All_Interrupts, "__gl_unreserve_all_interrupts");
-      Detect_Blocking : Integer;
-      pragma Import (C, Detect_Blocking, "__gl_detect_blocking");
-      Default_Stack_Size : Integer;
-      pragma Import (C, Default_Stack_Size, "__gl_default_stack_size");
-      Leap_Seconds_Support : Integer;
-      pragma Import (C, Leap_Seconds_Support, "__gl_leap_seconds_support");
-
-      procedure Runtime_Initialize;
-      pragma Import (C, Runtime_Initialize, "__gnat_runtime_initialize");
-
-      Finalize_Library_Objects : No_Param_Proc;
-      pragma Import (C, Finalize_Library_Objects, "__gnat_finalize_library_objects");
-
-   --  Start of processing for adainit
-
-   begin
-
-      --  Record various information for this partition.  The values
-      --  are derived by the binder from information stored in the ali
-      --  files by the compiler.
-
-      if Is_Elaborated then
-         return;
-      end if;
-      Is_Elaborated := True;
-      Main_Priority := -1;
-      Time_Slice_Value := -1;
-      WC_Encoding := 'b';
-      Locking_Policy := ' ';
-      Queuing_Policy := ' ';
-      Task_Dispatching_Policy := ' ';
-      Priority_Specific_Dispatching :=
-        Local_Priority_Specific_Dispatching'Address;
-      Num_Specific_Dispatching := 0;
-      Main_CPU := -1;
-      Interrupt_States := Local_Interrupt_States'Address;
-      Num_Interrupt_States := 0;
-      Unreserve_All_Interrupts := 0;
-      Detect_Blocking := 0;
-      Default_Stack_Size := -1;
-      Leap_Seconds_Support := 0;
-
-      Runtime_Initialize;
-
-      Finalize_Library_Objects := finalize_library'access;
-
-      --  Now we have the elaboration calls for all units in the partition.
-      --  The Elab_Spec and Elab_Body attributes generate references to the
-      --  implicit elaboration procedures generated by the compiler for
-      --  each unit that requires elaboration. Increment a counter of
-      --  reference for each unit.
-
-      System.Soft_Links'Elab_Spec;
-      System.Exception_Table'Elab_Body;
-      E23 := E23 + 1;
-      Ada.Io_Exceptions'Elab_Spec;
-      E46 := E46 + 1;
-      Ada.Tags'Elab_Spec;
-      Ada.Streams'Elab_Spec;
-      E45 := E45 + 1;
-      Interfaces.C'Elab_Spec;
-      System.Exceptions'Elab_Spec;
-      E25 := E25 + 1;
-      System.Finalization_Root'Elab_Spec;
-      E68 := E68 + 1;
-      Ada.Finalization'Elab_Spec;
-      E66 := E66 + 1;
-      System.Storage_Pools'Elab_Spec;
-      E85 := E85 + 1;
-      System.Finalization_Masters'Elab_Spec;
-      System.Storage_Pools.Subpools'Elab_Spec;
-      System.Pool_Global'Elab_Spec;
-      E87 := E87 + 1;
-      System.File_Control_Block'Elab_Spec;
-      E75 := E75 + 1;
-      System.File_Io'Elab_Body;
-      E64 := E64 + 1;
-      E91 := E91 + 1;
-      System.Finalization_Masters'Elab_Body;
-      E77 := E77 + 1;
-      E70 := E70 + 1;
-      Ada.Tags'Elab_Body;
-      E48 := E48 + 1;
-      System.Soft_Links'Elab_Body;
-      E13 := E13 + 1;
-      System.Os_Lib'Elab_Body;
-      E72 := E72 + 1;
-      System.Secondary_Stack'Elab_Body;
-      E17 := E17 + 1;
-      Ada.Text_Io'Elab_Spec;
-      Ada.Text_Io'Elab_Body;
-      E06 := E06 + 1;
-   end adainit;
-
-   --------------
-   -- adafinal --
-   --------------
-
-   procedure adafinal is
-      procedure s_stalib_adafinal;
-      pragma Import (C, s_stalib_adafinal, "system__standard_library__adafinal");
-
-      procedure Runtime_Finalize;
-      pragma Import (C, Runtime_Finalize, "__gnat_runtime_finalize");
-
-   begin
-      if not Is_Elaborated then
-         return;
-      end if;
-      Is_Elaborated := False;
-      Runtime_Finalize;
-      s_stalib_adafinal;
-   end adafinal;
-
-   --  We get to the main program of the partition by using
-   --  pragma Import because if we try to with the unit and
-   --  call it Ada style, then not only do we waste time
-   --  recompiling it, but also, we don't really know the right
-   --  switches (e.g.@@: identifier character set) to be used
-   --  to compile it.
-
-   procedure Ada_Main_Program;
-   pragma Import (Ada, Ada_Main_Program, "_ada_hello");
-
-   ----------
-   -- main --
-   ----------
-
-   --  main is actually a function, as in the ANSI C standard,
-   --  defined to return the exit status. The three parameters
-   --  are the argument count, argument values and environment
-   --  pointer.
-
-   function main
-     (argc : Integer;
-      argv : System.Address;
-      envp : System.Address)
-      return Integer
-   is
-      --  The initialize routine performs low level system
-      --  initialization using a standard library routine which
-      --  sets up signal handling and performs any other
-      --  required setup. The routine can be found in file
-      --  a-init.c.
-
-      procedure initialize;
-      pragma Import (C, initialize, "__gnat_initialize");
-
-      --  The finalize routine performs low level system
-      --  finalization using a standard library routine. The
-      --  routine is found in file a-final.c and in the standard
-      --  distribution is a dummy routine that does nothing, so
-      --  really this is a hook for special user finalization.
-
-      procedure finalize;
-      pragma Import (C, finalize, "__gnat_finalize");
-
-      --  The following is to initialize the SEH exceptions
-
-      SEH : aliased array (1 .. 2) of Integer;
-
-      Ensure_Reference : aliased System.Address := Ada_Main_Program_Name'Address;
-      pragma Volatile (Ensure_Reference);
-
-   --  Start of processing for main
-
-   begin
-      --  Save global variables
-
-      gnat_argc := argc;
-      gnat_argv := argv;
-      gnat_envp := envp;
-
-      --  Call low level system initialization
-
-      Initialize (SEH'Address);
-
-      --  Call our generated Ada initialization routine
-
-      adainit;
-
-      --  Now we call the main program of the partition
-
-      Ada_Main_Program;
-
-      --  Perform Ada finalization
-
-      adafinal;
-
-      --  Perform low level system finalization
-
-      Finalize;
-
-      --  Return the proper exit status
-      return (gnat_exit_status);
-   end;
-
---  This section is entirely comments, so it has no effect on the
---  compilation of the Ada_Main package. It provides the list of
---  object files and linker options, as well as some standard
---  libraries needed for the link. The gnatlink utility parses
---  this b~hello.adb file to read these comment lines to generate
---  the appropriate command line arguments for the call to the
---  system linker. The BEGIN/END lines are used for sentinels for
---  this parsing operation.
-
---  The exact file names will of course depend on the environment,
---  host/target and location of files on the host system.
-
--- BEGIN Object file/option list
-   --   ./hello.o
-   --   -L./
-   --   -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/
-   --   /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a
--- END Object file/option list
-
-end ada_main;
-@end example
-
-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 @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 @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 @code{Ada.Text_IO}. To locate this bug,
-you can place a breakpoint on the call:
-
-@quotation
-
-@example
-Ada.Text_Io'Elab_Body;
-@end example
-@end quotation
-
-and trace the elaboration routine for this package to find out where
-the problem might be (more usually of course you would be debugging
-elaboration code in your own application).
-
-@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 doc}@anchor{216}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{217}
-@chapter Elaboration Order Handling in GNAT
-
-
-@geindex Order of elaboration
-
-@geindex Elaboration control
-
-This appendix describes the handling of elaboration code in Ada and GNAT, and
-discusses how the order of elaboration of program units can be controlled in
-GNAT, either automatically or with explicit programming features.
-
-@menu
-* Elaboration Code:: 
-* Elaboration Order:: 
-* Checking the Elaboration Order:: 
-* Controlling the Elaboration Order in Ada:: 
-* Controlling the Elaboration Order in GNAT:: 
-* Mixing Elaboration Models:: 
-* ABE Diagnostics:: 
-* SPARK Diagnostics:: 
-* Elaboration Circularities:: 
-* Resolving Elaboration Circularities:: 
-* Elaboration-related Compiler Switches:: 
-* Summary of Procedures for Elaboration Control:: 
-* Inspecting the Chosen Elaboration Order:: 
-
-@end menu
-
-@node Elaboration Code,Elaboration Order,,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{218}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{219}
-@section Elaboration Code
-
-
-Ada defines the term `execution' as the process by which a construct achieves
-its run-time effect. This process is also referred to as `elaboration' for
-declarations and `evaluation' for expressions.
-
-The execution model in Ada allows for certain sections of an Ada program to be
-executed prior to execution of the program itself, primarily with the intent of
-initializing data. These sections are referred to as `elaboration code'.
-Elaboration code is executed as follows:
-
-
-@itemize *
-
-@item 
-All partitions of an Ada program are executed in parallel with one another,
-possibly in a separate address space, and possibly on a separate computer.
-
-@item 
-The execution of a partition involves running the environment task for that
-partition.
-
-@item 
-The environment task executes all elaboration code (if available) for all
-units within that partition. This code is said to be executed at
-`elaboration time'.
-
-@item 
-The environment task executes the Ada program (if available) for that
-partition.
-@end itemize
-
-In addition to the Ada terminology, this appendix defines the following terms:
-
-
-@itemize *
-
-@item 
-`Invocation'
-
-The act of calling a subprogram, instantiating a generic, or activating a
-task.
-
-@item 
-`Scenario'
-
-A construct that is elaborated or invoked by elaboration code is referred to
-as an `elaboration scenario' or simply a `scenario'. GNAT recognizes the
-following scenarios:
-
-
-@itemize -
-
-@item 
-@code{'Access} of entries, operators, and subprograms
-
-@item 
-Activation of tasks
-
-@item 
-Calls to entries, operators, and subprograms
-
-@item 
-Instantiations of generic templates
-@end itemize
-
-@item 
-`Target'
-
-A construct elaborated by a scenario is referred to as `elaboration target'
-or simply `target'. GNAT recognizes the following targets:
-
-
-@itemize -
-
-@item 
-For @code{'Access} of entries, operators, and subprograms, the target is the
-entry, operator, or subprogram being aliased.
-
-@item 
-For activation of tasks, the target is the task body
-
-@item 
-For calls to entries, operators, and subprograms, the target is the entry,
-operator, or subprogram being invoked.
-
-@item 
-For instantiations of generic templates, the target is the generic template
-being instantiated.
-@end itemize
-@end itemize
-
-Elaboration code may appear in two distinct contexts:
-
-
-@itemize *
-
-@item 
-`Library level'
-
-A scenario appears at the library level when it is encapsulated by a package
-[body] compilation unit, ignoring any other package [body] declarations in
-between.
-
-@example
-with Server;
-package Client is
-   procedure Proc;
-
-   package Nested is
-      Val : ... := Server.Func;
-   end Nested;
-end Client;
-@end example
-
-In the example above, the call to @code{Server.Func} is an elaboration scenario
-because it appears at the library level of package @code{Client}. Note that the
-declaration of package @code{Nested} is ignored according to the definition
-given above. As a result, the call to @code{Server.Func} will be invoked when
-the spec of unit @code{Client} is elaborated.
-
-@item 
-`Package body statements'
-
-A scenario appears within the statement sequence of a package body when it is
-bounded by the region starting from the @code{begin} keyword of the package body
-and ending at the @code{end} keyword of the package body.
-
-@example
-package body Client is
-   procedure Proc is
-   begin
-      ...
-   end Proc;
-begin
-   Proc;
-end Client;
-@end example
-
-In the example above, the call to @code{Proc} is an elaboration scenario because
-it appears within the statement sequence of package body @code{Client}. As a
-result, the call to @code{Proc} will be invoked when the body of @code{Client} is
-elaborated.
-@end itemize
-
-@node Elaboration Order,Checking the Elaboration Order,Elaboration Code,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order}@anchor{21a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{21b}
-@section Elaboration Order
-
-
-The sequence by which the elaboration code of all units within a partition is
-executed is referred to as `elaboration order'.
-
-Within a single unit, elaboration code is executed in sequential order.
-
-@quotation
-
-@example
-package body Client is
-   Result : ... := Server.Func;
-
-   procedure Proc is
-      package Inst is new Server.Gen;
-   begin
-      Inst.Eval (Result);
-   end Proc;
-begin
-   Proc;
-end Client;
-@end example
-@end quotation
-
-In the example above, the elaboration order within package body @code{Client} is
-as follows:
-
-
-@enumerate 
-
-@item 
-The object declaration of @code{Result} is elaborated.
-
-
-@itemize *
-
-@item 
-Function @code{Server.Func} is invoked.
-@end itemize
-
-@item 
-The subprogram body of @code{Proc} is elaborated.
-
-@item 
-Procedure @code{Proc} is invoked.
-
-
-@itemize *
-
-@item 
-Generic unit @code{Server.Gen} is instantiated as @code{Inst}.
-
-@item 
-Instance @code{Inst} is elaborated.
-
-@item 
-Procedure @code{Inst.Eval} is invoked.
-@end itemize
-@end enumerate
-
-The elaboration order of all units within a partition depends on the following
-factors:
-
-
-@itemize *
-
-@item 
-`with'ed units
-
-@item 
-parent units
-
-@item 
-purity of units
-
-@item 
-preelaborability of units
-
-@item 
-presence of elaboration-control pragmas
-
-@item 
-invocations performed in elaboration code
-@end itemize
-
-A program may have several elaboration orders depending on its structure.
-
-@quotation
-
-@example
-package Server is
-   function Func (Index : Integer) return Integer;
-end Server;
-@end example
-
-@example
-package body Server is
-   Results : array (1 .. 5) of Integer := (1, 2, 3, 4, 5);
-
-   function Func (Index : Integer) return Integer is
-   begin
-      return Results (Index);
-   end Func;
-end Server;
-@end example
-
-@example
-with Server;
-package Client is
-   Val : constant Integer := Server.Func (3);
-end Client;
-@end example
-
-@example
-with Client;
-procedure Main is begin null; end Main;
-@end example
-@end quotation
-
-The following elaboration order exhibits a fundamental problem referred to as
-`access-before-elaboration' or simply `ABE'.
-
-@quotation
-
-@example
-spec of Server
-spec of Client
-body of Server
-body of Main
-@end example
-@end quotation
-
-The elaboration of @code{Server}’s spec materializes function @code{Func}, making it
-callable. The elaboration of @code{Client}’s spec elaborates the declaration of
-@code{Val}. This invokes function @code{Server.Func}, however the body of
-@code{Server.Func} has not been elaborated yet because @code{Server}’s body comes
-after @code{Client}’s spec in the elaboration order. As a result, the value of
-constant @code{Val} is now undefined.
-
-Without any guarantees from the language, an undetected ABE problem may hinder
-proper initialization of data, which in turn may lead to undefined behavior at
-run time. To prevent such ABE problems, Ada employs dynamic checks in the same
-vein as index or null exclusion checks. A failed ABE check raises exception
-@code{Program_Error}.
-
-The following elaboration order avoids the ABE problem and the program can be
-successfully elaborated.
-
-@quotation
-
-@example
-spec of Server
-body of Server
-spec of Client
-body of Main
-@end example
-@end quotation
-
-Ada states that a total elaboration order must exist, but it does not define
-what this order is. A compiler is thus tasked with choosing a suitable
-elaboration order which satisfies the dependencies imposed by `with' clauses,
-unit categorization, elaboration-control pragmas, and invocations performed in
-elaboration code. Ideally an order that avoids ABE problems should be chosen,
-however a compiler may not always find such an order due to complications with
-respect to control and data flow.
-
-@node Checking the Elaboration Order,Controlling the Elaboration Order in Ada,Elaboration Order,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{21c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{21d}
-@section Checking the Elaboration Order
-
-
-To avoid placing the entire elaboration-order burden on the programmer, Ada
-provides three lines of defense:
-
-
-@itemize *
-
-@item 
-`Static semantics'
-
-Static semantic rules restrict the possible choice of elaboration order. For
-instance, if unit Client `with's unit Server, then the spec of Server is
-always elaborated prior to Client. The same principle applies to child units
-- the spec of a parent unit is always elaborated prior to the child unit.
-
-@item 
-`Dynamic semantics'
-
-Dynamic checks are performed at run time, to ensure that a target is
-elaborated prior to a scenario that invokes it, thus avoiding ABE problems.
-A failed run-time check raises exception @code{Program_Error}. The following
-restrictions apply:
-
-
-@itemize -
-
-@item 
-`Restrictions on calls'
-
-An entry, operator, or subprogram can be called from elaboration code only
-when the corresponding body has been elaborated.
-
-@item 
-`Restrictions on instantiations'
-
-A generic unit can be instantiated by elaboration code only when the
-corresponding body has been elaborated.
-
-@item 
-`Restrictions on task activation'
-
-A task can be activated by elaboration code only when the body of the
-associated task type has been elaborated.
-@end itemize
-
-The restrictions above can be summarized by the following rule:
-
-`If a target has a body, then this body must be elaborated prior to the
-scenario that invokes the target.'
-
-@item 
-`Elaboration control'
-
-Pragmas are provided for the programmer to specify the desired elaboration
-order.
-@end itemize
-
-@node Controlling the Elaboration Order in Ada,Controlling the Elaboration Order in GNAT,Checking the Elaboration Order,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-ada}@anchor{21e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{21f}
-@section Controlling the Elaboration Order in Ada
-
-
-Ada provides several idioms and pragmas to aid the programmer with specifying
-the desired elaboration order and avoiding ABE problems altogether.
-
-
-@itemize *
-
-@item 
-`Packages without a body'
-
-A library package which does not require a completing body does not suffer
-from ABE problems.
-
-@example
-package Pack is
-   generic
-      type Element is private;
-   package Containers is
-      type Element_Array is array (1 .. 10) of Element;
-   end Containers;
-end Pack;
-@end example
-
-In the example above, package @code{Pack} does not require a body because it
-does not contain any constructs which require completion in a body. As a
-result, generic @code{Pack.Containers} can be instantiated without encountering
-any ABE problems.
-@end itemize
-
-@geindex pragma Pure
-
-
-@itemize *
-
-@item 
-`pragma Pure'
-
-Pragma @code{Pure} places sufficient restrictions on a unit to guarantee that no
-scenario within the unit can result in an ABE problem.
-@end itemize
-
-@geindex pragma Preelaborate
-
-
-@itemize *
-
-@item 
-`pragma Preelaborate'
-
-Pragma @code{Preelaborate} is slightly less restrictive than pragma @code{Pure},
-but still strong enough to prevent ABE problems within a unit.
-@end itemize
-
-@geindex pragma Elaborate_Body
-
-
-@itemize *
-
-@item 
-`pragma Elaborate_Body'
-
-Pragma @code{Elaborate_Body} requires that the body of a unit is elaborated
-immediately after its spec. This restriction guarantees that no client
-scenario can invoke a server target before the target body has been
-elaborated because the spec and body are effectively “glued” together.
-
-@example
-package Server is
-   pragma Elaborate_Body;
-
-   function Func return Integer;
-end Server;
-@end example
-
-@example
-package body Server is
-   function Func return Integer is
-   begin
-      ...
-   end Func;
-end Server;
-@end example
-
-@example
-with Server;
-package Client is
-   Val : constant Integer := Server.Func;
-end Client;
-@end example
-
-In the example above, pragma @code{Elaborate_Body} guarantees the following
-elaboration order:
-
-@example
-spec of Server
-body of Server
-spec of Client
-@end example
-
-because the spec of @code{Server} must be elaborated prior to @code{Client} by
-virtue of the `with' clause, and in addition the body of @code{Server} must be
-elaborated immediately after the spec of @code{Server}.
-
-Removing pragma @code{Elaborate_Body} could result in the following incorrect
-elaboration order:
-
-@example
-spec of Server
-spec of Client
-body of Server
-@end example
-
-where @code{Client} invokes @code{Server.Func}, but the body of @code{Server.Func} has
-not been elaborated yet.
-@end itemize
-
-The pragmas outlined above allow a server unit to guarantee safe elaboration
-use by client units. Thus it is a good rule to mark units as @code{Pure} or
-@code{Preelaborate}, and if this is not possible, mark them as @code{Elaborate_Body}.
-
-There are however situations where @code{Pure}, @code{Preelaborate}, and
-@code{Elaborate_Body} are not applicable. Ada provides another set of pragmas for
-use by client units to help ensure the elaboration safety of server units they
-depend on.
-
-@geindex pragma Elaborate (Unit)
-
-
-@itemize *
-
-@item 
-`pragma Elaborate (Unit)'
-
-Pragma @code{Elaborate} can be placed in the context clauses of a unit, after a
-`with' clause. It guarantees that both the spec and body of its argument will
-be elaborated prior to the unit with the pragma. Note that other unrelated
-units may be elaborated in between the spec and the body.
-
-@example
-package Server is
-   function Func return Integer;
-end Server;
-@end example
-
-@example
-package body Server is
-   function Func return Integer is
-   begin
-      ...
-   end Func;
-end Server;
-@end example
-
-@example
-with Server;
-pragma Elaborate (Server);
-package Client is
-   Val : constant Integer := Server.Func;
-end Client;
-@end example
-
-In the example above, pragma @code{Elaborate} guarantees the following
-elaboration order:
-
-@example
-spec of Server
-body of Server
-spec of Client
-@end example
-
-Removing pragma @code{Elaborate} could result in the following incorrect
-elaboration order:
-
-@example
-spec of Server
-spec of Client
-body of Server
-@end example
-
-where @code{Client} invokes @code{Server.Func}, but the body of @code{Server.Func}
-has not been elaborated yet.
-@end itemize
-
-@geindex pragma Elaborate_All (Unit)
-
-
-@itemize *
-
-@item 
-`pragma Elaborate_All (Unit)'
-
-Pragma @code{Elaborate_All} is placed in the context clauses of a unit, after
-a `with' clause. It guarantees that both the spec and body of its argument
-will be elaborated prior to the unit with the pragma, as well as all units
-`with'ed by the spec and body of the argument, recursively. Note that other
-unrelated units may be elaborated in between the spec and the body.
-
-@example
-package Math is
-   function Factorial (Val : Natural) return Natural;
-end Math;
-@end example
-
-@example
-package body Math is
-   function Factorial (Val : Natural) return Natural is
-   begin
-      ...;
-   end Factorial;
-end Math;
-@end example
-
-@example
-package Computer is
-   type Operation_Kind is (None, Op_Factorial);
-
-   function Compute
-     (Val : Natural;
-      Op  : Operation_Kind) return Natural;
-end Computer;
-@end example
-
-@example
-with Math;
-package body Computer is
-   function Compute
-     (Val : Natural;
-      Op  : Operation_Kind) return Natural
-   is
-      if Op = Op_Factorial then
-         return Math.Factorial (Val);
-      end if;
-
-      return 0;
-   end Compute;
-end Computer;
-@end example
-
-@example
-with Computer;
-pragma Elaborate_All (Computer);
-package Client is
-   Val : constant Natural :=
-           Computer.Compute (123, Computer.Op_Factorial);
-end Client;
-@end example
-
-In the example above, pragma @code{Elaborate_All} can result in the following
-elaboration order:
-
-@example
-spec of Math
-body of Math
-spec of Computer
-body of Computer
-spec of Client
-@end example
-
-Note that there are several allowable suborders for the specs and bodies of
-@code{Math} and @code{Computer}, but the point is that these specs and bodies will
-be elaborated prior to @code{Client}.
-
-Removing pragma @code{Elaborate_All} could result in the following incorrect
-elaboration order:
-
-@example
-spec of Math
-spec of Computer
-body of Computer
-spec of Client
-body of Math
-@end example
-
-where @code{Client} invokes @code{Computer.Compute}, which in turn invokes
-@code{Math.Factorial}, but the body of @code{Math.Factorial} has not been
-elaborated yet.
-@end itemize
-
-All pragmas shown above can be summarized by the following rule:
-
-`If a client unit elaborates a server target directly or indirectly, then if
-the server unit requires a body and does not have pragma Pure, Preelaborate,
-or Elaborate_Body, then the client unit should have pragma Elaborate or
-Elaborate_All for the server unit.'
-
-If the rule outlined above is not followed, then a program may fall in one of
-the following states:
-
-
-@itemize *
-
-@item 
-`No elaboration order exists'
-
-In this case a compiler must diagnose the situation, and refuse to build an
-executable program.
-
-@item 
-`One or more incorrect elaboration orders exist'
-
-In this case a compiler can build an executable program, but
-@code{Program_Error} will be raised when the program is run.
-
-@item 
-`Several elaboration orders exist, some correct, some incorrect'
-
-In this case the programmer has not controlled the elaboration order. As a
-result, a compiler may or may not pick one of the correct orders, and the
-program may or may not raise @code{Program_Error} when it is run. This is the
-worst possible state because the program may fail on another compiler, or
-even another version of the same compiler.
-
-@item 
-`One or more correct orders exist'
-
-In this case a compiler can build an executable program, and the program is
-run successfully. This state may be guaranteed by following the outlined
-rules, or may be the result of good program architecture.
-@end itemize
-
-Note that one additional advantage of using @code{Elaborate} and @code{Elaborate_All}
-is that the program continues to stay in the last state (one or more correct
-orders exist) even if maintenance changes the bodies of targets.
-
-@node Controlling the Elaboration Order in GNAT,Mixing Elaboration Models,Controlling the Elaboration Order in Ada,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-gnat}@anchor{220}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{221}
-@section Controlling the Elaboration Order in GNAT
-
-
-In addition to Ada semantics and rules synthesized from them, GNAT offers
-three elaboration models to aid the programmer with specifying the correct
-elaboration order and to diagnose elaboration problems.
-
-@geindex Dynamic elaboration model
-
-
-@itemize *
-
-@item 
-`Dynamic elaboration model'
-
-This is the most permissive of the three elaboration models and emulates the
-behavior specified by the Ada Reference Manual. When the dynamic model is in
-effect, GNAT makes the following assumptions:
-
-
-@itemize -
-
-@item 
-All code within all units in a partition is considered to be elaboration
-code.
-
-@item 
-Some of the invocations in elaboration code may not take place at run time
-due to conditional execution.
-@end itemize
-
-GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
-that invoke internal targets. In addition, GNAT generates run-time checks for
-all external targets and for all scenarios that may exhibit ABE problems.
-
-The elaboration order is obtained by honoring all `with' clauses, purity and
-preelaborability of units, and elaboration-control pragmas. The dynamic model
-attempts to take all invocations in elaboration code into account. If an
-invocation leads to a circularity, GNAT ignores the invocation based on the
-assumptions stated above. An order obtained using the dynamic model may fail
-an ABE check at run time when GNAT ignored an invocation.
-
-The dynamic model is enabled with compiler switch @code{-gnatE}.
-@end itemize
-
-@geindex Static elaboration model
-
-
-@itemize *
-
-@item 
-`Static elaboration model'
-
-This is the middle ground of the three models. When the static model is in
-effect, GNAT makes the following assumptions:
-
-
-@itemize -
-
-@item 
-Only code at the library level and in package body statements within all
-units in a partition is considered to be elaboration code.
-
-@item 
-All invocations in elaboration will take place at run time, regardless of
-conditional execution.
-@end itemize
-
-GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
-that invoke internal targets. In addition, GNAT generates run-time checks for
-all external targets and for all scenarios that may exhibit ABE problems.
-
-The elaboration order is obtained by honoring all `with' clauses, purity and
-preelaborability of units, presence of elaboration-control pragmas, and all
-invocations in elaboration code. An order obtained using the static model is
-guaranteed to be ABE problem-free, excluding dispatching calls and
-access-to-subprogram types.
-
-The static model is the default model in GNAT.
-@end itemize
-
-@geindex SPARK elaboration model
-
-
-@itemize *
-
-@item 
-`SPARK elaboration model'
-
-This is the most conservative of the three models and enforces the SPARK
-rules of elaboration as defined in the SPARK Reference Manual, section 7.7.
-The SPARK model is in effect only when a scenario and a target reside in a
-region subject to @code{SPARK_Mode On}, otherwise the dynamic or static model
-is in effect.
-
-The SPARK model is enabled with compiler switch @code{-gnatd.v}.
-@end itemize
-
-@geindex Legacy elaboration models
-
-
-@itemize *
-
-@item 
-`Legacy elaboration models'
-
-In addition to the three elaboration models outlined above, GNAT provides the
-following legacy models:
-
-
-@itemize -
-
-@item 
-@cite{Legacy elaboration-checking model} available in pre-18.x versions of GNAT.
-This model is enabled with compiler switch @code{-gnatH}.
-
-@item 
-@cite{Legacy elaboration-order model} available in pre-20.x versions of GNAT.
-This model is enabled with binder switch @code{-H}.
-@end itemize
-@end itemize
-
-@geindex Relaxed elaboration mode
-
-The dynamic, legacy, and static models can be relaxed using compiler switch
-@code{-gnatJ}, making them more permissive. Note that in this mode, GNAT
-may not diagnose certain elaboration issues or install run-time checks.
-
-@node Mixing Elaboration Models,ABE Diagnostics,Controlling the Elaboration Order in GNAT,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{222}@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{223}
-@section Mixing Elaboration Models
-
-
-It is possible to mix units compiled with a different elaboration model,
-however the following rules must be observed:
-
-
-@itemize *
-
-@item 
-A client unit compiled with the dynamic model can only `with' a server unit
-that meets at least one of the following criteria:
-
-
-@itemize -
-
-@item 
-The server unit is compiled with the dynamic model.
-
-@item 
-The server unit is a GNAT implementation unit from the @code{Ada}, @code{GNAT},
-@code{Interfaces}, or @code{System} hierarchies.
-
-@item 
-The server unit has pragma @code{Pure} or @code{Preelaborate}.
-
-@item 
-The client unit has an explicit @code{Elaborate_All} pragma for the server
-unit.
-@end itemize
-@end itemize
-
-These rules ensure that elaboration checks are not omitted. If the rules are
-violated, the binder emits a warning:
-
-@quotation
-
-@example
-warning: "x.ads" has dynamic elaboration checks and with's
-warning:   "y.ads" which has static elaboration checks
-@end example
-@end quotation
-
-The warnings can be suppressed by binder switch @code{-ws}.
-
-@node ABE Diagnostics,SPARK Diagnostics,Mixing Elaboration Models,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat abe-diagnostics}@anchor{224}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{225}
-@section ABE Diagnostics
-
-
-GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
-that invoke internal targets, regardless of whether the dynamic, SPARK, or
-static model is in effect.
-
-Note that GNAT emits warnings rather than hard errors whenever it encounters an
-elaboration problem. This is because the elaboration model in effect may be too
-conservative, or a particular scenario may not be invoked due conditional
-execution. The warnings can be suppressed selectively with @code{pragma Warnings
-(Off)} or globally with compiler switch @code{-gnatwL}.
-
-A `guaranteed ABE' arises when the body of a target is not elaborated early
-enough, and causes `all' scenarios that directly invoke the target to fail.
-
-@quotation
-
-@example
-package body Guaranteed_ABE is
-   function ABE return Integer;
-
-   Val : constant Integer := ABE;
-
-   function ABE return Integer is
-   begin
-     ...
-   end ABE;
-end Guaranteed_ABE;
-@end example
-@end quotation
-
-In the example above, the elaboration of @code{Guaranteed_ABE}’s body elaborates
-the declaration of @code{Val}. This invokes function @code{ABE}, however the body of
-@code{ABE} has not been elaborated yet. GNAT emits the following diagnostic:
-
-@quotation
-
-@example
-4.    Val : constant Integer := ABE;
-                                |
-   >>> warning: cannot call "ABE" before body seen
-   >>> warning: Program_Error will be raised at run time
-@end example
-@end quotation
-
-A `conditional ABE' arises when the body of a target is not elaborated early
-enough, and causes `some' scenarios that directly invoke the target to fail.
-
-@quotation
-
-@example
- 1. package body Conditional_ABE is
- 2.    procedure Force_Body is null;
- 3.
- 4.    generic
- 5.       with function Func return Integer;
- 6.    package Gen is
- 7.       Val : constant Integer := Func;
- 8.    end Gen;
- 9.
-10.    function ABE return Integer;
-11.
-12.    function Cause_ABE return Boolean is
-13.       package Inst is new Gen (ABE);
-14.    begin
-15.       ...
-16.    end Cause_ABE;
-17.
-18.    Val : constant Boolean := Cause_ABE;
-19.
-20.    function ABE return Integer is
-21.    begin
-22.       ...
-23.    end ABE;
-24.
-25.    Safe : constant Boolean := Cause_ABE;
-26. end Conditional_ABE;
-@end example
-@end quotation
-
-In the example above, the elaboration of package body @code{Conditional_ABE}
-elaborates the declaration of @code{Val}. This invokes function @code{Cause_ABE},
-which instantiates generic unit @code{Gen} as @code{Inst}. The elaboration of
-@code{Inst} invokes function @code{ABE}, however the body of @code{ABE} has not been
-elaborated yet. GNAT emits the following diagnostic:
-
-@quotation
-
-@example
-13.       package Inst is new Gen (ABE);
-          |
-    >>> warning: in instantiation at line 7
-    >>> warning: cannot call "ABE" before body seen
-    >>> warning: Program_Error may be raised at run time
-    >>> warning:   body of unit "Conditional_ABE" elaborated
-    >>> warning:   function "Cause_ABE" called at line 18
-    >>> warning:   function "ABE" called at line 7, instance at line 13
-@end example
-@end quotation
-
-Note that the same ABE problem does not occur with the elaboration of
-declaration @code{Safe} because the body of function @code{ABE} has already been
-elaborated at that point.
-
-@node SPARK Diagnostics,Elaboration Circularities,ABE Diagnostics,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{226}@anchor{gnat_ugn/elaboration_order_handling_in_gnat spark-diagnostics}@anchor{227}
-@section SPARK Diagnostics
-
-
-GNAT enforces the SPARK rules of elaboration as defined in the SPARK Reference
-Manual section 7.7 when compiler switch @code{-gnatd.v} is in effect. Note
-that GNAT emits hard errors whenever it encounters a violation of the SPARK
-rules.
-
-@quotation
-
-@example
-1. with Server;
-2. package body SPARK_Diagnostics with SPARK_Mode is
-3.    Val : constant Integer := Server.Func;
-                                      |
-   >>> call to "Func" during elaboration in SPARK
-   >>> unit "SPARK_Diagnostics" requires pragma "Elaborate_All" for "Server"
-   >>>   body of unit "SPARK_Model" elaborated
-   >>>   function "Func" called at line 3
-
-4. end SPARK_Diagnostics;
-@end example
-@end quotation
-
-@node Elaboration Circularities,Resolving Elaboration Circularities,SPARK Diagnostics,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-circularities}@anchor{228}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{229}
-@section Elaboration Circularities
-
-
-An `elaboration circularity' occurs whenever the elaboration of a set of
-units enters a deadlocked state, where each unit is waiting for another unit
-to be elaborated. This situation may be the result of improper use of `with'
-clauses, elaboration-control pragmas, or invocations in elaboration code.
-
-The following example exhibits an elaboration circularity.
-
-@quotation
-
-@example
-with B; pragma Elaborate (B);
-package A is
-end A;
-@end example
-
-@example
-package B is
-   procedure Force_Body;
-end B;
-@end example
-
-@example
-with C;
-package body B is
-   procedure Force_Body is null;
-
-   Elab : constant Integer := C.Func;
-end B;
-@end example
-
-@example
-package C is
-   function Func return Integer;
-end C;
-@end example
-
-@example
-with A;
-package body C is
-   function Func return Integer is
-   begin
-      ...
-   end Func;
-end C;
-@end example
-@end quotation
-
-The binder emits the following diagnostic:
-
-@quotation
-
-@example
-error: Elaboration circularity detected
-info:
-info:    Reason:
-info:
-info:      unit "a (spec)" depends on its own elaboration
-info:
-info:    Circularity:
-info:
-info:      unit "a (spec)" has with clause and pragma Elaborate for unit "b (spec)"
-info:      unit "b (body)" is in the closure of pragma Elaborate
-info:      unit "b (body)" invokes a construct of unit "c (body)" at elaboration time
-info:      unit "c (body)" has with clause for unit "a (spec)"
-info:
-info:    Suggestions:
-info:
-info:      remove pragma Elaborate for unit "b (body)" in unit "a (spec)"
-info:      use the dynamic elaboration model (compiler switch -gnatE)
-@end example
-@end quotation
-
-The diagnostic consist of the following sections:
-
-
-@itemize *
-
-@item 
-Reason
-
-This section provides a short explanation describing why the set of units
-could not be ordered.
-
-@item 
-Circularity
-
-This section enumerates the units comprising the deadlocked set, along with
-their interdependencies.
-
-@item 
-Suggestions
-
-This section enumerates various tactics for eliminating the circularity.
-@end itemize
-
-@node Resolving Elaboration Circularities,Elaboration-related Compiler Switches,Elaboration Circularities,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{22a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat resolving-elaboration-circularities}@anchor{22b}
-@section Resolving Elaboration Circularities
-
-
-The most desirable option from the point of view of long-term maintenance is to
-rearrange the program so that the elaboration problems are avoided. One useful
-technique is to place the elaboration code into separate child packages.
-Another is to move some of the initialization code to explicitly invoked
-subprograms, where the program controls the order of initialization explicitly.
-Although this is the most desirable option, it may be impractical and involve
-too much modification, especially in the case of complex legacy code.
-
-When faced with an elaboration circularity, the programmer should also consider
-the tactics given in the suggestions section of the circularity diagnostic.
-Depending on the units involved in the circularity, their `with' clauses,
-purity, preelaborability, presence of elaboration-control pragmas and
-invocations at elaboration time, the binder may suggest one or more of the
-following tactics to eliminate the circularity:
-
-
-@itemize *
-
-@item 
-Pragma Elaborate elimination
-
-@example
-remove pragma Elaborate for unit "..." in unit "..."
-@end example
-
-This tactic is suggested when the binder has determined that pragma
-@code{Elaborate}:
-
-
-@itemize -
-
-@item 
-Prevents a set of units from being elaborated.
-
-@item 
-The removal of the pragma will not eliminate the semantic effects of the
-pragma. In other words, the argument of the pragma will still be elaborated
-prior to the unit containing the pragma.
-
-@item 
-The removal of the pragma will enable the successful ordering of the units.
-@end itemize
-
-The programmer should remove the pragma as advised, and rebuild the program.
-
-@item 
-Pragma Elaborate_All elimination
-
-@example
-remove pragma Elaborate_All for unit "..." in unit "..."
-@end example
-
-This tactic is suggested when the binder has determined that pragma
-@code{Elaborate_All}:
-
-
-@itemize -
-
-@item 
-Prevents a set of units from being elaborated.
-
-@item 
-The removal of the pragma will not eliminate the semantic effects of the
-pragma. In other words, the argument of the pragma along with its `with'
-closure will still be elaborated prior to the unit containing the pragma.
-
-@item 
-The removal of the pragma will enable the successful ordering of the units.
-@end itemize
-
-The programmer should remove the pragma as advised, and rebuild the program.
-
-@item 
-Pragma Elaborate_All downgrade
-
-@example
-change pragma Elaborate_All for unit "..." to Elaborate in unit "..."
-@end example
-
-This tactic is always suggested with the pragma @code{Elaborate_All} elimination
-tactic. It offers a different alternative of guaranteeing that the argument
-of the pragma will still be elaborated prior to the unit containing the
-pragma.
-
-The programmer should update the pragma as advised, and rebuild the program.
-
-@item 
-Pragma Elaborate_Body elimination
-
-@example
-remove pragma Elaborate_Body in unit "..."
-@end example
-
-This tactic is suggested when the binder has determined that pragma
-@code{Elaborate_Body}:
-
-
-@itemize -
-
-@item 
-Prevents a set of units from being elaborated.
-
-@item 
-The removal of the pragma will enable the successful ordering of the units.
-@end itemize
-
-Note that the binder cannot determine whether the pragma is required for
-other purposes, such as guaranteeing the initialization of a variable
-declared in the spec by elaboration code in the body.
-
-The programmer should remove the pragma as advised, and rebuild the program.
-
-@item 
-Use of pragma Restrictions
-
-@example
-use pragma Restrictions (No_Entry_Calls_In_Elaboration_Code)
-@end example
-
-This tactic is suggested when the binder has determined that a task
-activation at elaboration time:
-
-
-@itemize -
-
-@item 
-Prevents a set of units from being elaborated.
-@end itemize
-
-Note that the binder cannot determine with certainty whether the task will
-block at elaboration time.
-
-The programmer should create a configuration file, place the pragma within,
-update the general compilation arguments, and rebuild the program.
-
-@item 
-Use of dynamic elaboration model
-
-@example
-use the dynamic elaboration model (compiler switch -gnatE)
-@end example
-
-This tactic is suggested when the binder has determined that an invocation at
-elaboration time:
-
-
-@itemize -
-
-@item 
-Prevents a set of units from being elaborated.
-
-@item 
-The use of the dynamic model will enable the successful ordering of the
-units.
-@end itemize
-
-The programmer has two options:
-
-
-@itemize -
-
-@item 
-Determine the units involved in the invocation using the detailed
-invocation information, and add compiler switch @code{-gnatE} to the
-compilation arguments of selected files only. This approach will yield
-safer elaboration orders compared to the other option because it will
-minimize the opportunities presented to the dynamic model for ignoring
-invocations.
-
-@item 
-Add compiler switch @code{-gnatE} to the general compilation arguments.
-@end itemize
-
-@item 
-Use of detailed invocation information
-
-@example
-use detailed invocation information (compiler switch -gnatd_F)
-@end example
-
-This tactic is always suggested with the use of the dynamic model tactic. It
-causes the circularity section of the circularity diagnostic to describe the
-flow of elaboration code from a unit to a unit, enumerating all such paths in
-the process.
-
-The programmer should analyze this information to determine which units
-should be compiled with the dynamic model.
-
-@item 
-Forced-dependency elimination
-
-@example
-remove the dependency of unit "..." on unit "..." from the argument of switch -f
-@end example
-
-This tactic is suggested when the binder has determined that a dependency
-present in the forced-elaboration-order file indicated by binder switch
-@code{-f}:
-
-
-@itemize -
-
-@item 
-Prevents a set of units from being elaborated.
-
-@item 
-The removal of the dependency will enable the successful ordering of the
-units.
-@end itemize
-
-The programmer should edit the forced-elaboration-order file, remove the
-dependency, and rebind the program.
-
-@item 
-All forced-dependency elimination
-
-@example
-remove switch -f
-@end example
-
-This tactic is suggested in case editing the forced-elaboration-order file is
-not an option.
-
-The programmer should remove binder switch @code{-f} from the binder
-arguments, and rebind.
-
-@item 
-Multiple-circularities diagnostic
-
-@example
-diagnose all circularities (binder switch -d_C)
-@end example
-
-By default, the binder will diagnose only the highest-precedence circularity.
-If the program contains multiple circularities, the binder will suggest the
-use of binder switch @code{-d_C} in order to obtain the diagnostics of all
-circularities.
-
-The programmer should add binder switch @code{-d_C} to the binder
-arguments, and rebind.
-@end itemize
-
-If none of the tactics suggested by the binder eliminate the elaboration
-circularity, the programmer should consider using one of the legacy elaboration
-models, in the following order:
-
-
-@itemize *
-
-@item 
-Use the pre-20.x legacy elaboration-order model, with binder switch
-@code{-H}.
-
-@item 
-Use both pre-18.x and pre-20.x legacy elaboration models, with compiler
-switch @code{-gnatH} and binder switch @code{-H}.
-
-@item 
-Use the relaxed static-elaboration model, with compiler switches
-@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}.
-
-@item 
-Use the relaxed dynamic-elaboration model, with compiler switches
-@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch
-@code{-H}.
-@end itemize
-
-@node Elaboration-related Compiler Switches,Summary of Procedures for Elaboration Control,Resolving Elaboration Circularities,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-related-compiler-switches}@anchor{22c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{22d}
-@section Elaboration-related Compiler Switches
-
-
-GNAT has several switches that affect the elaboration model and consequently
-the elaboration order chosen by the binder.
-
-@geindex -gnatE (gnat)
-
-
-@table @asis
-
-@item @code{-gnatE}
-
-Dynamic elaboration checking mode enabled
-
-When this switch is in effect, GNAT activates the dynamic model.
-@end table
-
-@geindex -gnatel (gnat)
-
-
-@table @asis
-
-@item @code{-gnatel}
-
-Turn on info messages on generated Elaborate[_All] pragmas
-
-This switch is only applicable to the pre-20.x legacy elaboration models.
-The post-20.x elaboration model no longer relies on implicitly generated
-@code{Elaborate} and @code{Elaborate_All} pragmas to order units.
-
-When this switch is in effect, GNAT will emit the following supplementary
-information depending on the elaboration model in effect.
-
-
-@itemize -
-
-@item 
-`Dynamic model'
-
-GNAT will indicate missing @code{Elaborate} and @code{Elaborate_All} pragmas for
-all library-level scenarios within the partition.
-
-@item 
-`Static model'
-
-GNAT will indicate all scenarios invoked during elaboration. In addition,
-it will provide detailed traceback when an implicit @code{Elaborate} or
-@code{Elaborate_All} pragma is generated.
-
-@item 
-`SPARK model'
-
-GNAT will indicate how an elaboration requirement is met by the context of
-a unit. This diagnostic requires compiler switch @code{-gnatd.v}.
-
-@example
-1. with Server; pragma Elaborate_All (Server);
-2. package Client with SPARK_Mode is
-3.    Val : constant Integer := Server.Func;
-                                      |
-   >>> info: call to "Func" during elaboration in SPARK
-   >>> info: "Elaborate_All" requirement for unit "Server" met by pragma at line 1
-
-4. end Client;
-@end example
-@end itemize
-@end table
-
-@geindex -gnatH (gnat)
-
-
-@table @asis
-
-@item @code{-gnatH}
-
-Legacy elaboration checking mode enabled
-
-When this switch is in effect, GNAT will utilize the pre-18.x elaboration
-model.
-@end table
-
-@geindex -gnatJ (gnat)
-
-
-@table @asis
-
-@item @code{-gnatJ}
-
-Relaxed elaboration checking mode enabled
-
-When this switch is in effect, GNAT will not process certain scenarios,
-resulting in a more permissive elaboration model. Note that this may
-eliminate some diagnostics and run-time checks.
-@end table
-
-@geindex -gnatw.f (gnat)
-
-
-@table @asis
-
-@item @code{-gnatw.f}
-
-Turn on warnings for suspicious Subp’Access
-
-When this switch is in effect, GNAT will treat @code{'Access} of an entry,
-operator, or subprogram as a potential call to the target and issue warnings:
-
-@example
- 1. package body Attribute_Call is
- 2.    function Func return Integer;
- 3.    type Func_Ptr is access function return Integer;
- 4.
- 5.    Ptr : constant Func_Ptr := Func'Access;
-                                      |
-    >>> warning: "Access" attribute of "Func" before body seen
-    >>> warning: possible Program_Error on later references
-    >>> warning:   body of unit "Attribute_Call" elaborated
-    >>> warning:   "Access" of "Func" taken at line 5
-
- 6.
- 7.    function Func return Integer is
- 8.    begin
- 9.       ...
-10.    end Func;
-11. end Attribute_Call;
-@end example
-
-In the example above, the elaboration of declaration @code{Ptr} is assigned
-@code{Func'Access} before the body of @code{Func} has been elaborated.
-@end table
-
-@geindex -gnatwl (gnat)
-
-
-@table @asis
-
-@item @code{-gnatwl}
-
-Turn on warnings for elaboration problems
-
-When this switch is in effect, GNAT emits diagnostics in the form of warnings
-concerning various elaboration problems. The warnings are enabled by default.
-The switch is provided in case all warnings are suppressed, but elaboration
-warnings are still desired.
-
-@item @code{-gnatwL}
-
-Turn off warnings for elaboration problems
-
-When this switch is in effect, GNAT no longer emits any diagnostics in the
-form of warnings. Selective suppression of elaboration problems is possible
-using @code{pragma Warnings (Off)}.
-
-@example
- 1. package body Selective_Suppression is
- 2.    function ABE return Integer;
- 3.
- 4.    Val_1 : constant Integer := ABE;
-                                   |
-    >>> warning: cannot call "ABE" before body seen
-    >>> warning: Program_Error will be raised at run time
-
- 5.
- 6.    pragma Warnings (Off);
- 7.    Val_2 : constant Integer := ABE;
- 8.    pragma Warnings (On);
- 9.
-10.    function ABE return Integer is
-11.    begin
-12.       ...
-13.    end ABE;
-14. end Selective_Suppression;
-@end example
-
-Note that suppressing elaboration warnings does not eliminate run-time
-checks. The example above will still fail at run time with an ABE.
-@end table
-
-@node Summary of Procedures for Elaboration Control,Inspecting the Chosen Elaboration Order,Elaboration-related Compiler Switches,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{22e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{22f}
-@section Summary of Procedures for Elaboration Control
-
-
-A programmer should first compile the program with the default options, using
-none of the binder or compiler switches. If the binder succeeds in finding an
-elaboration order, then apart from possible cases involving dispatching calls
-and access-to-subprogram types, the program is free of elaboration errors.
-
-If it is important for the program to be portable to compilers other than GNAT,
-then the programmer should use compiler switch @code{-gnatel} and consider
-the messages about missing or implicitly created @code{Elaborate} and
-@code{Elaborate_All} pragmas.
-
-If the binder reports an elaboration circularity, the programmer has several
-options:
-
-
-@itemize *
-
-@item 
-Ensure that elaboration warnings are enabled. This will allow the static
-model to output trace information of elaboration issues. The trace
-information could shed light on previously unforeseen dependencies, as well
-as their origins. Elaboration warnings are enabled with compiler switch
-@code{-gnatwl}.
-
-@item 
-Cosider the tactics given in the suggestions section of the circularity
-diagnostic.
-
-@item 
-If none of the steps outlined above resolve the circularity, use a more
-permissive elaboration model, in the following order:
-
-
-@itemize -
-
-@item 
-Use the pre-20.x legacy elaboration-order model, with binder switch
-@code{-H}.
-
-@item 
-Use both pre-18.x and pre-20.x legacy elaboration models, with compiler
-switch @code{-gnatH} and binder switch @code{-H}.
-
-@item 
-Use the relaxed static elaboration model, with compiler switches
-@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}.
-
-@item 
-Use the relaxed dynamic elaboration model, with compiler switches
-@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch
-@code{-H}.
-@end itemize
-@end itemize
-
-@node Inspecting 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{230}@anchor{gnat_ugn/elaboration_order_handling_in_gnat inspecting-the-chosen-elaboration-order}@anchor{231}
-@section Inspecting the Chosen Elaboration Order
-
-
-To see the elaboration order chosen by the binder, inspect the contents of file
-@cite{b~xxx.adb}. On certain targets, this file appears as @cite{b_xxx.adb}. The
-elaboration order appears as a sequence of calls to @code{Elab_Body} and
-@code{Elab_Spec}, interspersed with assignments to @cite{Exxx} which indicates that a
-particular unit is elaborated. For example:
-
-@quotation
-
-@example
-System.Soft_Links'Elab_Body;
-E14 := True;
-System.Secondary_Stack'Elab_Body;
-E18 := True;
-System.Exception_Table'Elab_Body;
-E24 := True;
-Ada.Io_Exceptions'Elab_Spec;
-E67 := True;
-Ada.Tags'Elab_Spec;
-Ada.Streams'Elab_Spec;
-E43 := True;
-Interfaces.C'Elab_Spec;
-E69 := True;
-System.Finalization_Root'Elab_Spec;
-E60 := True;
-System.Os_Lib'Elab_Body;
-E71 := True;
-System.Finalization_Implementation'Elab_Spec;
-System.Finalization_Implementation'Elab_Body;
-E62 := True;
-Ada.Finalization'Elab_Spec;
-E58 := True;
-Ada.Finalization.List_Controller'Elab_Spec;
-E76 := True;
-System.File_Control_Block'Elab_Spec;
-E74 := True;
-System.File_Io'Elab_Body;
-E56 := True;
-Ada.Tags'Elab_Body;
-E45 := True;
-Ada.Text_Io'Elab_Spec;
-Ada.Text_Io'Elab_Body;
-E07 := True;
-@end example
-@end quotation
-
-Note also binder switch @code{-l}, which outputs the chosen elaboration
-order and provides a more readable form of the above:
-
-@quotation
-
-@example
-ada (spec)
-interfaces (spec)
-system (spec)
-system.case_util (spec)
-system.case_util (body)
-system.concat_2 (spec)
-system.concat_2 (body)
-system.concat_3 (spec)
-system.concat_3 (body)
-system.htable (spec)
-system.parameters (spec)
-system.parameters (body)
-system.crtl (spec)
-interfaces.c_streams (spec)
-interfaces.c_streams (body)
-system.restrictions (spec)
-system.restrictions (body)
-system.standard_library (spec)
-system.exceptions (spec)
-system.exceptions (body)
-system.storage_elements (spec)
-system.storage_elements (body)
-system.secondary_stack (spec)
-system.stack_checking (spec)
-system.stack_checking (body)
-system.string_hash (spec)
-system.string_hash (body)
-system.htable (body)
-system.strings (spec)
-system.strings (body)
-system.traceback (spec)
-system.traceback (body)
-system.traceback_entries (spec)
-system.traceback_entries (body)
-ada.exceptions (spec)
-ada.exceptions.last_chance_handler (spec)
-system.soft_links (spec)
-system.soft_links (body)
-ada.exceptions.last_chance_handler (body)
-system.secondary_stack (body)
-system.exception_table (spec)
-system.exception_table (body)
-ada.io_exceptions (spec)
-ada.tags (spec)
-ada.streams (spec)
-interfaces.c (spec)
-interfaces.c (body)
-system.finalization_root (spec)
-system.finalization_root (body)
-system.memory (spec)
-system.memory (body)
-system.standard_library (body)
-system.os_lib (spec)
-system.os_lib (body)
-system.unsigned_types (spec)
-system.stream_attributes (spec)
-system.stream_attributes (body)
-system.finalization_implementation (spec)
-system.finalization_implementation (body)
-ada.finalization (spec)
-ada.finalization (body)
-ada.finalization.list_controller (spec)
-ada.finalization.list_controller (body)
-system.file_control_block (spec)
-system.file_io (spec)
-system.file_io (body)
-system.val_uns (spec)
-system.val_util (spec)
-system.val_util (body)
-system.val_uns (body)
-system.wch_con (spec)
-system.wch_con (body)
-system.wch_cnv (spec)
-system.wch_jis (spec)
-system.wch_jis (body)
-system.wch_cnv (body)
-system.wch_stw (spec)
-system.wch_stw (body)
-ada.tags (body)
-ada.exceptions (body)
-ada.text_io (spec)
-ada.text_io (body)
-text_io (spec)
-gdbstr (body)
-@end example
-@end quotation
-
-@node Inline Assembler,GNU Free Documentation License,Elaboration Order Handling in GNAT,Top
-@anchor{gnat_ugn/inline_assembler doc}@anchor{232}@anchor{gnat_ugn/inline_assembler id1}@anchor{233}@anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{10}
-@chapter Inline Assembler
-
-
-@geindex Inline Assembler
-
-If you need to write low-level software that interacts directly
-with the hardware, Ada provides two ways to incorporate assembly
-language code into your program.  First, you can import and invoke
-external routines written in assembly language, an Ada feature fully
-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 @code{System.Machine_Code}, which incorporates the gcc
-Inline Assembler.  The Inline Assembler approach offers a number of advantages,
-including the following:
-
-
-@itemize *
-
-@item 
-No need to use non-Ada tools
-
-@item 
-Consistent interface over different targets
-
-@item 
-Automatic usage of the proper calling conventions
-
-@item 
-Access to Ada constants and variables
-
-@item 
-Definition of intrinsic routines
-
-@item 
-Possibility of inlining a subprogram comprising assembler code
-
-@item 
-Code optimizer can take Inline Assembler code into account
-@end itemize
-
-This appendix presents a series of examples to show you how to use
-the Inline Assembler.  Although it focuses on the Intel x86,
-the general approach applies also to other processors.
-It is assumed that you are familiar with Ada
-and with assembly language programming.
-
-@menu
-* Basic Assembler Syntax:: 
-* A Simple Example of Inline Assembler:: 
-* Output Variables in Inline Assembler:: 
-* Input Variables in Inline Assembler:: 
-* Inlining Inline Assembler Code:: 
-* Other Asm Functionality:: 
-
-@end menu
-
-@node Basic Assembler Syntax,A Simple Example of Inline Assembler,,Inline Assembler
-@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{234}@anchor{gnat_ugn/inline_assembler id2}@anchor{235}
-@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 @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 @code{as} and @code{gas} (an @code{as} macro
-pre-processor) documentation for further information.
-
-
-@display
-`Register names'@w{ }
-@display
-gcc / @code{as}: Prefix with ‘%’; for example @code{%eax}@w{ }
-Intel: No extra punctuation; for example @code{eax}@w{ }
-@end display
-@end display
-
-
-
-
-@display
-`Immediate operand'@w{ }
-@display
-gcc / @code{as}: Prefix with ‘$’; for example @code{$4}@w{ }
-Intel: No extra punctuation; for example @code{4}@w{ }
-@end display
-@end display
-
-
-
-
-@display
-`Address'@w{ }
-@display
-gcc / @code{as}: Prefix with ‘$’; for example @code{$loc}@w{ }
-Intel: No extra punctuation; for example @code{loc}@w{ }
-@end display
-@end display
-
-
-
-
-@display
-`Memory contents'@w{ }
-@display
-gcc / @code{as}: No extra punctuation; for example @code{loc}@w{ }
-Intel: Square brackets; for example @code{[loc]}@w{ }
-@end display
-@end display
-
-
-
-
-@display
-`Register contents'@w{ }
-@display
-gcc / @code{as}: Parentheses; for example @code{(%eax)}@w{ }
-Intel: Square brackets; for example @code{[eax]}@w{ }
-@end display
-@end display
-
-
-
-
-@display
-`Hexadecimal numbers'@w{ }
-@display
-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
-`Operand size'@w{ }
-@display
-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
-`Instruction repetition'@w{ }
-@display
-gcc / @code{as}: Split into two lines; for example@w{ }
-@display
-@code{rep}@w{ }
-@code{stosl}@w{ }
-@end display
-Intel: Keep on one line; for example @code{rep stosl}@w{ }
-@end display
-@end display
-
-
-
-
-@display
-`Order of operands'@w{ }
-@display
-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{236}@anchor{gnat_ugn/inline_assembler id3}@anchor{237}
-@section A Simple Example of Inline Assembler
-
-
-The following example will generate a single assembly language statement,
-@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.
-
-@quotation
-
-@example
-with System.Machine_Code; use System.Machine_Code;
-procedure Nothing is
-begin
-   Asm ("nop");
-end Nothing;
-@end example
-@end quotation
-
-@code{Asm} is a procedure declared in package @code{System.Machine_Code};
-here it takes one parameter, a `template string' that must be a static
-expression and that will form the generated instruction.
-@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 @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 @code{Nothing} procedure
-should be in a file named @code{nothing.adb}.
-You can build the executable in the usual way:
-
-@quotation
-
-@example
-$ gnatmake nothing
-@end example
-@end quotation
-
-However, the interesting aspect of this example is not its run-time behavior
-but rather the generated assembly code.
-To see this output, invoke the compiler as follows:
-
-@quotation
-
-@example
-$ gcc -c -S -fomit-frame-pointer -gnatp nothing.adb
-@end example
-@end quotation
-
-where the options are:
-
-
-@itemize *
-
-@item 
-
-@table @asis
-
-@item @code{-c}
-
-compile only (no bind or link)
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{-S}
-
-generate assembler listing
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{-fomit-frame-pointer}
-
-do not set up separate stack frames
-@end table
-
-@item 
-
-@table @asis
-
-@item @code{-gnatp}
-
-do not add runtime checks
-@end table
-@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 @code{.s}
-extension. In our example, the file @code{nothing.s} has the following
-contents:
-
-@quotation
-
-@example
-.file "nothing.adb"
-gcc2_compiled.:
-___gnu_compiled_ada:
-.text
-   .align 4
-.globl __ada_nothing
-__ada_nothing:
-#APP
-   nop
-#NO_APP
-   jmp L1
-   .align 2,0x90
-L1:
-   ret
-@end example
-@end quotation
-
-The assembly code you included is clearly indicated by
-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’.
-
-If you make a mistake in your assembler code (such as using the
-wrong size modifier, or using a wrong operand for the instruction) GNAT
-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
-@code{as} assembler that comes with gcc.
-
-Assembling the file using the command
-
-@quotation
-
-@example
-$ as nothing.s
-@end example
-@end quotation
-
-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, @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{238}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{239}
-@section Output Variables in Inline Assembler
-
-
-The examples in this section, showing how to access the processor flags,
-illustrate how to specify the destination operands for assembly language
-statements.
-
-@quotation
-
-@example
-with Interfaces; use Interfaces;
-with Ada.Text_IO; use Ada.Text_IO;
-with System.Machine_Code; use System.Machine_Code;
-procedure Get_Flags is
-   Flags : Unsigned_32;
-   use ASCII;
-begin
-   Asm ("pushfl"          & LF & HT & -- push flags on stack
-        "popl %%eax"      & LF & HT & -- load eax with flags
-        "movl %%eax, %0",             -- store flags in variable
-        Outputs => Unsigned_32'Asm_Output ("=g", Flags));
-   Put_Line ("Flags register:" & Flags'Img);
-end Get_Flags;
-@end example
-@end quotation
-
-In order to have a nicely aligned assembly listing, we have separated
-multiple assembler statements in the Asm template string with linefeed
-(ASCII.LF) and horizontal tab (ASCII.HT) characters.
-The resulting section of the assembly output file is:
-
-@quotation
-
-@example
-#APP
-   pushfl
-   popl %eax
-   movl %eax, -40(%ebp)
-#NO_APP
-@end example
-@end quotation
-
-It would have been legal to write the Asm invocation as:
-
-@quotation
-
-@example
-Asm ("pushfl popl %%eax movl %%eax, %0")
-@end example
-@end quotation
-
-but in the generated assembler file, this would come out as:
-
-@quotation
-
-@example
-#APP
-   pushfl popl %eax movl %eax, -40(%ebp)
-#NO_APP
-@end example
-@end quotation
-
-which is not so convenient for the human reader.
-
-We use Ada comments
-at the end of each line to explain what the assembler instructions
-actually do.  This is a useful convention.
-
-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 @code{%%eax}.
-In the generated assembly code, one of the percent signs will be stripped off.
-
-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:
-
-@quotation
-
-@example
-movl %%eax, %0
-@end example
-@end quotation
-
-The intent is to store the contents of the eax register in a variable that can
-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 @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 @code{%0} output variable.
-
-Information about the output variable is supplied in the @code{Outputs}
-parameter to @code{Asm}:
-
-@quotation
-
-@example
-Outputs => Unsigned_32'Asm_Output ("=g", Flags));
-@end example
-@end quotation
-
-The output is defined by the @code{Asm_Output} attribute of the target type;
-the general format is
-
-@quotation
-
-@example
-Type'Asm_Output (constraint_string, variable_name)
-@end example
-@end quotation
-
-The constraint string directs the compiler how
-to store/access the associated variable.  In the example
-
-@quotation
-
-@example
-Unsigned_32'Asm_Output ("=m", Flags);
-@end example
-@end quotation
-
-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
-
-@example
-Unsigned_32'Asm_Output ("=r", Flags);
-@end example
-@end quotation
-
-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 @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
-most useful (for the Intel x86 processor) are the following:
-
-@quotation
-
-
-@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
-@item
-
-`='
-
-@tab
-
-output constraint
-
-@item
-
-`g'
-
-@tab
-
-global (i.e., can be stored anywhere)
-
-@item
-
-`m'
-
-@tab
-
-in memory
-
-@item
-
-`I'
-
-@tab
-
-a constant
-
-@item
-
-`a'
-
-@tab
-
-use eax
-
-@item
-
-`b'
-
-@tab
-
-use ebx
-
-@item
-
-`c'
-
-@tab
-
-use ecx
-
-@item
-
-`d'
-
-@tab
-
-use edx
-
-@item
-
-`S'
-
-@tab
-
-use esi
-
-@item
-
-`D'
-
-@tab
-
-use edi
-
-@item
-
-`r'
-
-@tab
-
-use one of eax, ebx, ecx or edx
-
-@item
-
-`q'
-
-@tab
-
-use one of eax, ebx, ecx, edx, esi or edi
-
-@end multitable
-
-@end quotation
-
-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.
-
-You specify the association of an output variable with an assembler operand
-through the @code{%@var{n}} notation, where `n' is a non-negative
-integer.  Thus in
-
-@quotation
-
-@example
-Asm ("pushfl"          & LF & HT & -- push flags on stack
-     "popl %%eax"      & LF & HT & -- load eax with flags
-     "movl %%eax, %0",             -- store flags in variable
-     Outputs => Unsigned_32'Asm_Output ("=g", Flags));
-@end example
-@end quotation
-
-@code{%0} will be replaced in the expanded code by the appropriate operand,
-whatever
-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 @code{%0}, @code{%1}, etc.
-
-@item 
-Specify the @code{Outputs} parameter as a parenthesized comma-separated list
-of @code{Asm_Output} attributes
-@end itemize
-
-For example:
-
-@quotation
-
-@example
-Asm ("movl %%eax, %0" & LF & HT &
-     "movl %%ebx, %1" & LF & HT &
-     "movl %%ecx, %2",
-     Outputs => (Unsigned_32'Asm_Output ("=g", Var_A),   --  %0 = Var_A
-                 Unsigned_32'Asm_Output ("=g", Var_B),   --  %1 = Var_B
-                 Unsigned_32'Asm_Output ("=g", Var_C))); --  %2 = Var_C
-@end example
-@end quotation
-
-where @code{Var_A}, @code{Var_B}, and @code{Var_C} are variables
-in the Ada program.
-
-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
-@code{Asm} template string:
-
-@quotation
-
-@example
-with Interfaces; use Interfaces;
-with Ada.Text_IO; use Ada.Text_IO;
-with System.Machine_Code; use System.Machine_Code;
-procedure Get_Flags_2 is
-   Flags : Unsigned_32;
-   use ASCII;
-begin
-   Asm ("pushfl"      & LF & HT & -- push flags on stack
-        "popl %%eax",             -- save flags in eax
-        Outputs => Unsigned_32'Asm_Output ("=a", Flags));
-   Put_Line ("Flags register:" & Flags'Img);
-end Get_Flags_2;
-@end example
-@end quotation
-
-The @code{"a"} constraint tells the compiler that the @code{Flags}
-variable will come from the eax register. Here is the resulting code:
-
-@quotation
-
-@example
-#APP
-   pushfl
-   popl %eax
-#NO_APP
-   movl %eax,-40(%ebp)
-@end example
-@end quotation
-
-The compiler generated the store of eax into Flags after
-expanding the assembler code.
-
-Actually, there was no need to pop the flags into the eax register;
-more simply, we could just pop the flags directly into the program variable:
-
-@quotation
-
-@example
-with Interfaces; use Interfaces;
-with Ada.Text_IO; use Ada.Text_IO;
-with System.Machine_Code; use System.Machine_Code;
-procedure Get_Flags_3 is
-   Flags : Unsigned_32;
-   use ASCII;
-begin
-   Asm ("pushfl"  & LF & HT & -- push flags on stack
-        "pop %0",             -- save flags in Flags
-        Outputs => Unsigned_32'Asm_Output ("=g", Flags));
-   Put_Line ("Flags register:" & Flags'Img);
-end Get_Flags_3;
-@end example
-@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{23a}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{23b}
-@section Input Variables in Inline Assembler
-
-
-The example in this section illustrates how to specify the source operands
-for assembly language statements.
-The program simply increments its input value by 1:
-
-@quotation
-
-@example
-with Interfaces; use Interfaces;
-with Ada.Text_IO; use Ada.Text_IO;
-with System.Machine_Code; use System.Machine_Code;
-procedure Increment is
-
-   function Incr (Value : Unsigned_32) return Unsigned_32 is
-      Result : Unsigned_32;
-   begin
-      Asm ("incl %0",
-           Outputs => Unsigned_32'Asm_Output ("=a", Result),
-           Inputs  => Unsigned_32'Asm_Input ("a", Value));
-      return Result;
-   end Incr;
-
-   Value : Unsigned_32;
-
-begin
-   Value := 5;
-   Put_Line ("Value before is" & Value'Img);
-   Value := Incr (Value);
-  Put_Line ("Value after is" & Value'Img);
-end Increment;
-@end example
-@end quotation
-
-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 @code{Result} variable.
-
-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 @code{Outputs} parameter causes the register to be stored into the
-target variable after execution of the assembler statements, so does the
-@code{Inputs} parameter cause its variable to be loaded into the register
-before execution of the assembler statements.
-
-Thus the effect of the @code{Asm} invocation is:
-
-
-@itemize *
-
-@item 
-load the 32-bit value of @code{Value} into eax
-
-@item 
-execute the @code{incl %eax} instruction
-
-@item 
-store the contents of eax into the @code{Result} variable
-@end itemize
-
-The resulting assembler file (with @code{-O2} optimization) contains:
-
-@quotation
-
-@example
-_increment__incr.1:
-   subl $4,%esp
-   movl 8(%esp),%eax
-#APP
-   incl %eax
-#NO_APP
-   movl %eax,%edx
-   movl %ecx,(%esp)
-   addl $4,%esp
-   ret
-@end example
-@end quotation
-
-@node Inlining Inline Assembler Code,Other Asm Functionality,Input Variables in Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id6}@anchor{23c}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{23d}
-@section Inlining Inline Assembler Code
-
-
-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 @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:
-
-@quotation
-
-@example
-with Interfaces; use Interfaces;
-with Ada.Text_IO; use Ada.Text_IO;
-with System.Machine_Code; use System.Machine_Code;
-procedure Increment_2 is
-
-   function Incr (Value : Unsigned_32) return Unsigned_32 is
-      Result : Unsigned_32;
-   begin
-      Asm ("incl %0",
-           Outputs => Unsigned_32'Asm_Output ("=a", Result),
-           Inputs  => Unsigned_32'Asm_Input ("a", Value));
-      return Result;
-   end Incr;
-   pragma Inline (Increment);
-
-   Value : Unsigned_32;
-
-begin
-   Value := 5;
-   Put_Line ("Value before is" & Value'Img);
-   Value := Increment (Value);
-   Put_Line ("Value after is" & Value'Img);
-end Increment_2;
-@end example
-@end quotation
-
-Compile the program with both optimization (@code{-O2}) and inlining
-(@code{-gnatn}) enabled.
-
-The @code{Incr} function is still compiled as usual, but at the
-point in @code{Increment} where our function used to be called:
-
-@quotation
-
-@example
-pushl %edi
-call _increment__incr.1
-@end example
-@end quotation
-
-the code for the function body directly appears:
-
-@quotation
-
-@example
-movl %esi,%eax
-#APP
-   incl %eax
-#NO_APP
-   movl %eax,%edx
-@end example
-@end 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 id7}@anchor{23e}@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{23f}
-@section Other @code{Asm} Functionality
-
-
-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:: 
-* The Volatile Parameter:: 
-
-@end menu
-
-@node The Clobber Parameter,The Volatile Parameter,,Other Asm Functionality
-@anchor{gnat_ugn/inline_assembler id8}@anchor{240}@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{241}
-@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.,
-@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 @code{mull}
-storing its result in both eax and edx).
-It can also arise from explicit register usage in your
-assembly code; for example:
-
-@quotation
-
-@example
-Asm ("movl %0, %%ebx" & LF & HT &
-     "movl %%ebx, %1",
-     Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
-     Inputs  => Unsigned_32'Asm_Input  ("g", Var_In));
-@end example
-@end quotation
-
-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 @code{Clobber} parameter to @code{Asm},
-to identify the registers that will be used by your assembly code:
-
-@quotation
-
-@example
-Asm ("movl %0, %%ebx" & LF & HT &
-     "movl %%ebx, %1",
-     Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
-     Inputs  => Unsigned_32'Asm_Input  ("g", Var_In),
-     Clobber => "ebx");
-@end example
-@end quotation
-
-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., @code{"eax, ebx"}
-
-The @code{Clobber} parameter has several additional uses:
-
-
-@itemize *
-
-@item 
-Use ‘register’ name @code{cc} to indicate that flags might have changed
-
-@item 
-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 id9}@anchor{242}@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{243}
-@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 @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 @code{Volatile} parameter to @code{True}; for example:
-
-@quotation
-
-@example
-Asm ("movl %0, %%ebx" & LF & HT &
-     "movl %%ebx, %1",
-     Outputs  => Unsigned_32'Asm_Output ("=g", Var_Out),
-     Inputs   => Unsigned_32'Asm_Input  ("g", Var_In),
-     Clobber  => "ebx",
-     Volatile => True);
-@end example
-@end quotation
-
-By default, @code{Volatile} is set to @code{False} unless there is no
-@code{Outputs} parameter.
-
-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 @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 doc}@anchor{244}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{245}
-@chapter GNU Free Documentation License
-
-
-Version 1.3, 3 November 2008
-
-Copyright  2000, 2001, 2002, 2007, 2008  Free Software Foundation, Inc
-@indicateurl{https://fsf.org/}
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-
-`Preamble'
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document “free” in the sense of freedom: to
-assure everyone the effective freedom to copy and redistribute it,
-with or without modifying it, either commercially or noncommercially.
-Secondarily, this License preserves for the author and publisher a way
-to get credit for their work, while not being considered responsible
-for modifications made by others.
-
-This License is a kind of “copyleft”, which means that derivative
-works of the document must themselves be free in the same sense.  It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does.  But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book.  We recommend this License
-principally for works whose purpose is instruction or reference.
-
-`1. APPLICABILITY AND DEFINITIONS'
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License.  Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein.  The `Document', below,
-refers to any such manual or work.  Any member of the public is a
-licensee, and is addressed as “`you'”.  You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-A “`Modified Version'” of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A “`Secondary Section'” is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document’s overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject.  (Thus, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.)  The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The “`Invariant Sections'” are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License.  If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant.  The Document may contain zero
-Invariant Sections.  If the Document does not identify any Invariant
-Sections then there are none.
-
-The “`Cover Texts'” are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License.  A Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A “`Transparent'” copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters.  A copy made in an otherwise Transparent file
-format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text.  A copy that is not “Transparent” is called `Opaque'.
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML, PostScript or PDF designed for human modification.  Examples of
-transparent image formats include PNG, XCF and JPG.  Opaque formats
-include proprietary formats that can be read and edited only by
-proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated HTML, PostScript or PDF produced by some word
-processors for output purposes only.
-
-The “`Title Page'” means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page.  For works in
-formats which do not have any title page as such, “Title Page” means
-the text near the most prominent appearance of the work’s title,
-preceding the beginning of the body of the text.
-
-The “`publisher'” means any person or entity that distributes
-copies of the Document to the public.
-
-A section “`Entitled XYZ'” means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language.  (Here XYZ stands for a
-specific section name mentioned below, such as “`Acknowledgements'”,
-“`Dedications'”, “`Endorsements'”, or “`History'”.)
-To “`Preserve the Title'”
-of such a section when you modify the Document means that it remains a
-section “Entitled XYZ” according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document.  These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-
-`2. VERBATIM COPYING'
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License.  You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute.  However, you may accept
-compensation in exchange for copies.  If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
-`3. COPYING IN QUANTITY'
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) of the Document, numbering more than 100, and the
-Document’s license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover.  Both covers must also clearly and legibly identify
-you as the publisher of these copies.  The front cover must present
-the full title with all words of the title equally prominent and
-visible.  You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-If you use the latter option, you must take reasonably prudent steps,
-when you begin distribution of Opaque copies in quantity, to ensure
-that this Transparent copy will remain thus accessible at the stated
-location until at least one year after the last time you distribute an
-Opaque copy (directly or through your agents or retailers) of that
-edition to the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
-`4. MODIFICATIONS'
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it.  In addition, you must do these things in the Modified Version:
-
-
-@enumerate A
-
-@item 
-Use in the Title Page (and on the covers, if any) a title distinct
-from that of the Document, and from those of previous versions
-(which should, if there were any, be listed in the History section
-of the Document).  You may use the same title as a previous version
-if the original publisher of that version gives permission.
-
-@item 
-List on the Title Page, as authors, one or more persons or entities
-responsible for authorship of the modifications in the Modified
-Version, together with at least five of the principal authors of the
-Document (all of its principal authors, if it has fewer than five),
-unless they release you from this requirement.
-
-@item 
-State on the Title page the name of the publisher of the
-Modified Version, as the publisher.
-
-@item 
-Preserve all the copyright notices of the Document.
-
-@item 
-Add an appropriate copyright notice for your modifications
-adjacent to the other copyright notices.
-
-@item 
-Include, immediately after the copyright notices, a license notice
-giving the public permission to use the Modified Version under the
-terms of this License, in the form shown in the Addendum below.
-
-@item 
-Preserve in that license notice the full lists of Invariant Sections
-and required Cover Texts given in the Document’s license notice.
-
-@item 
-Include an unaltered copy of this License.
-
-@item 
-Preserve the section Entitled “History”, Preserve its Title, and add
-to it an item stating at least the title, year, new authors, and
-publisher of the Modified Version as given on the Title Page.  If
-there is no section Entitled “History” in the Document, create one
-stating the title, year, authors, and publisher of the Document as
-given on its Title Page, then add an item describing the Modified
-Version as stated in the previous sentence.
-
-@item 
-Preserve the network location, if any, given in the Document for
-public access to a Transparent copy of the Document, and likewise
-the network locations given in the Document for previous versions
-it was based on.  These may be placed in the “History” section.
-You may omit a network location for a work that was published at
-least four years before the Document itself, or if the original
-publisher of the version it refers to gives permission.
-
-@item 
-For any section Entitled “Acknowledgements” or “Dedications”,
-Preserve the Title of the section, and preserve in the section all
-the substance and tone of each of the contributor acknowledgements
-and/or dedications given therein.
-
-@item 
-Preserve all the Invariant Sections of the Document,
-unaltered in their text and in their titles.  Section numbers
-or the equivalent are not considered part of the section titles.
-
-@item 
-Delete any section Entitled “Endorsements”.  Such a section
-may not be included in the Modified Version.
-
-@item 
-Do not retitle any existing section to be Entitled “Endorsements”
-or to conflict in title with any Invariant Section.
-
-@item 
-Preserve any Warranty Disclaimers.
-@end enumerate
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant.  To do this, add their titles to the
-list of Invariant Sections in the Modified Version’s license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section Entitled “Endorsements”, provided it contains
-nothing but endorsements of your Modified Version by various
-parties—for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version.  Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity.  If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
-`5. COMBINING DOCUMENTS'
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice, and that you preserve all their Warranty Disclaimers.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy.  If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled “History”
-in the various original documents, forming one section Entitled
-“History”; likewise combine any sections Entitled “Acknowledgements”,
-and any sections Entitled “Dedications”.  You must delete all sections
-Entitled “Endorsements”.
-
-`6. COLLECTIONS OF DOCUMENTS'
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
-`7. AGGREGATION WITH INDEPENDENT WORKS'
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, is called an “aggregate” if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation’s users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which are not themselves
-derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one half of
-the entire aggregate, the Document’s Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-
-`8. TRANSLATION'
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections.  You may include a
-translation of this License, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers.  In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled “Acknowledgements”,
-“Dedications”, or “History”, the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-
-`9. TERMINATION'
-
-You may not copy, modify, sublicense, or distribute the Document
-except as expressly provided under this License.  Any attempt
-otherwise to copy, modify, sublicense, or distribute it is void, and
-will automatically terminate your rights under this License.
-
-However, if you cease all violation of this License, then your license
-from a particular copyright holder is reinstated (a) provisionally,
-unless and until the copyright holder explicitly and finally
-terminates your license, and (b) permanently, if the copyright holder
-fails to notify you of the violation by some reasonable means prior to
-60 days after the cessation.
-
-Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, receipt of a copy of some or all of the same material does
-not give you any rights to use it.
-
-`10. FUTURE REVISIONS OF THIS LICENSE'
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time.  Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.  See
-@indicateurl{https://www.gnu.org/copyleft/}.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License “or any later version” applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation.  If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.  If the Document
-specifies that a proxy can decide which future versions of this
-License can be used, that proxy’s public statement of acceptance of a
-version permanently authorizes you to choose that version for the
-Document.
-
-`11. RELICENSING'
-
-“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
-World Wide Web server that publishes copyrightable works and also
-provides prominent facilities for anybody to edit those works.  A
-public wiki that anybody can edit is an example of such a server.  A
-“Massive Multiauthor Collaboration” (or “MMC”) contained in the
-site means any set of copyrightable works thus published on the MMC
-site.
-
-“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
-license published by Creative Commons Corporation, a not-for-profit
-corporation with a principal place of business in San Francisco,
-California, as well as future copyleft versions of that license
-published by that same organization.
-
-“Incorporate” means to publish or republish a Document, in whole or
-in part, as part of another Document.
-
-An MMC is “eligible for relicensing” if it is licensed under this
-License, and if all works that were first published under this License
-somewhere other than this MMC, and subsequently incorporated in whole
-or in part into the MMC, (1) had no cover texts or invariant sections,
-and (2) were thus incorporated prior to November 1, 2008.
-
-The operator of an MMC Site may republish an MMC contained in the site
-under CC-BY-SA on the same site at any time before August 1, 2009,
-provided the MMC is eligible for relicensing.
-
-`ADDENDUM: How to use this License for your documents'
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
-@quotation
-
-Copyright © YEAR  YOUR NAME.
-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, no Front-Cover Texts, and no Back-Cover Texts.
-A copy of the license is included in the section entitled “GNU
-Free Documentation License”.
-@end quotation
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the “with … Texts.” line with this:
-
-@quotation
-
-with the Invariant Sections being LIST THEIR TITLES, with the
-Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-@end quotation
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
-@node Index,,GNU Free Documentation License,Top
-@unnumbered Index
-
-
-@printindex ge
-
-@anchor{cf}@w{                              }
-@anchor{gnat_ugn/gnat_utility_programs switches-related-to-project-files}@w{                              }
-
-@c %**end of body
-@bye