From: Martin Liska Date: Sun, 13 Nov 2022 20:59:18 +0000 (+0100) Subject: Revert "sphinx: ada: port to Sphinx" X-Git-Tag: basepoints/gcc-14~3216 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=64d5610f44c995b88261bf83f53a200355cb530f;p=thirdparty%2Fgcc.git Revert "sphinx: ada: port to Sphinx" This reverts commit 0a543515957ff47feba739e6f71062fb2fb99125. --- diff --git a/gcc/ada/doc/Makefile b/gcc/ada/doc/Makefile new file mode 100644 index 000000000000..4adfd368cc8d --- /dev/null +++ b/gcc/ada/doc/Makefile @@ -0,0 +1,87 @@ +# 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 ' where 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/index.rst b/gcc/ada/doc/gnat-style.rst similarity index 99% rename from gcc/ada/doc/gnat-style/index.rst rename to gcc/ada/doc/gnat-style.rst index b9428749f1f8..527e7ba2a66d 100644 --- a/gcc/ada/doc/gnat-style/index.rst +++ b/gcc/ada/doc/gnat-style.rst @@ -688,4 +688,4 @@ Program Structure and Compilation Issues .. index:: krunch.ads file .. toctree:: - gnu_free_documentation_license + share/gnu_free_documentation_license diff --git a/gcc/ada/doc/gnat-style/conf.py b/gcc/ada/doc/gnat-style/conf.py deleted file mode 100644 index a413d2632eb1..000000000000 --- a/gcc/ada/doc/gnat-style/conf.py +++ /dev/null @@ -1,26 +0,0 @@ -# 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 deleted file mode 100644 index 33c62cf7fde6..000000000000 --- a/gcc/ada/doc/gnat-style/gnu_free_documentation_license.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../../doc/gnu_free_documentation_license.rst diff --git a/gcc/ada/doc/gnat_rm/index.rst b/gcc/ada/doc/gnat_rm.rst similarity index 54% rename from gcc/ada/doc/gnat_rm/index.rst rename to gcc/ada/doc/gnat_rm.rst index 6c2616a0f1c0..7743ef8b5f43 100644 --- a/gcc/ada/doc/gnat_rm/index.rst +++ b/gcc/ada/doc/gnat_rm.rst @@ -39,25 +39,25 @@ GNAT Reference Manual :numbered: :maxdepth: 3 - 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 + 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 .. raw:: latex @@ -66,4 +66,4 @@ GNAT Reference Manual .. toctree:: :maxdepth: 3 - gnu_free_documentation_license + share/gnu_free_documentation_license diff --git a/gcc/ada/doc/gnat_rm/conf.py b/gcc/ada/doc/gnat_rm/conf.py deleted file mode 100644 index e99d1e6bd134..000000000000 --- a/gcc/ada/doc/gnat_rm/conf.py +++ /dev/null @@ -1,26 +0,0 @@ -# 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 deleted file mode 100644 index 33c62cf7fde6..000000000000 --- a/gcc/ada/doc/gnat_rm/gnu_free_documentation_license.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../../doc/gnu_free_documentation_license.rst diff --git a/gcc/ada/doc/gnat_rm/security_hardening_features.rst b/gcc/ada/doc/gnat_rm/security_hardening_features.rst index 5a1f2d46326e..d7c02b94f36d 100644 --- a/gcc/ada/doc/gnat_rm/security_hardening_features.rst +++ b/gcc/ada/doc/gnat_rm/security_hardening_features.rst @@ -1,5 +1,3 @@ -.. role:: switch(samp) - .. _Security_Hardening_Features: *************************** diff --git a/gcc/ada/doc/gnat_ugn/index.rst b/gcc/ada/doc/gnat_ugn.rst similarity index 63% rename from gcc/ada/doc/gnat_ugn/index.rst rename to gcc/ada/doc/gnat_ugn.rst index d3d1dac3569e..0ac68763760f 100644 --- a/gcc/ada/doc/gnat_ugn/index.rst +++ b/gcc/ada/doc/gnat_ugn.rst @@ -40,12 +40,12 @@ GNAT User's Guide for Native Platforms :maxdepth: 3 :numbered: - about_this_guide - getting_started_with_gnat - the_gnat_compilation_model - building_executable_programs_with_gnat - gnat_utility_programs - gnat_and_program_execution + 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 .. raw:: latex @@ -54,10 +54,10 @@ GNAT User's Guide for Native Platforms .. toctree:: :maxdepth: 3 - A. Platform-Specific Information - B. Example of Binder Output - C. Elaboration Order Handling in GNAT - D. Inline Assembler - E. GNU Free Documentation License + A. Platform-Specific Information + B. Example of Binder Output + C. Elaboration Order Handling in GNAT + D. Inline Assembler + E. GNU Free Documentation License diff --git a/gcc/ada/doc/gnat_ugn/conf.py b/gcc/ada/doc/gnat_ugn/conf.py deleted file mode 100644 index 94e3c07e836d..000000000000 --- a/gcc/ada/doc/gnat_ugn/conf.py +++ /dev/null @@ -1,26 +0,0 @@ -# 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 deleted file mode 100644 index 33c62cf7fde6..000000000000 --- a/gcc/ada/doc/gnat_ugn/gnu_free_documentation_license.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../../doc/gnu_free_documentation_license.rst diff --git a/gcc/ada/doc/gnat_ugn/platform_specific_information.rst b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst index 3ada65ddade0..4d25dea3d1e7 100644 --- a/gcc/ada/doc/gnat_ugn/platform_specific_information.rst +++ b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst @@ -1,5 +1,11 @@ .. 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/adabaseconf.py b/gcc/ada/doc/share/adabaseconf.py deleted file mode 100644 index 4a80a838c633..000000000000 --- a/gcc/ada/doc/share/adabaseconf.py +++ /dev/null @@ -1,81 +0,0 @@ -# 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 new file mode 100644 index 000000000000..bb36bfa0c6a7 --- /dev/null +++ b/gcc/ada/doc/share/conf.py @@ -0,0 +1,148 @@ +# -*- 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 new file mode 100644 index 000000000000..0235545155f4 --- /dev/null +++ b/gcc/ada/doc/share/gnu_free_documentation_license.rst @@ -0,0 +1,458 @@ +.. _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/doc/share/ada_latex_elements.py b/gcc/ada/doc/share/latex_elements.py similarity index 87% rename from gcc/ada/doc/share/ada_latex_elements.py rename to gcc/ada/doc/share/latex_elements.py index 9578c0296af4..f23b2aff6be1 100644 --- a/gcc/ada/doc/share/ada_latex_elements.py +++ b/gcc/ada/doc/share/latex_elements.py @@ -1,9 +1,5 @@ # 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{%% @@ -50,7 +46,7 @@ TOC_CMD = r''' \makeatother ''' -with open(os.path.join(folder, 'copyright.tex'), 'r') as fd: +with open('copyright.tex', 'r') as fd: copyright = fd.read() TOC = r''' @@ -66,11 +62,6 @@ 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/gcc-interface/Make-lang.in b/gcc/ada/gcc-interface/Make-lang.in index 71a26e526277..45a4168e8908 100644 --- a/gcc/ada/gcc-interface/Make-lang.in +++ b/gcc/ada/gcc-interface/Make-lang.in @@ -808,24 +808,32 @@ ada.tags: force # Generate documentation. -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; \ +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 $@ $<; \ else true; fi -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; \ +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 $@ $<; \ else true; fi -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; \ +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 $@ $<; \ else true; fi -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_INFOFILES = doc/gnat_ugn.info doc/gnat_rm.info doc/gnat-style.info ada.info: $(ADA_INFOFILES) @@ -836,33 +844,26 @@ ada.install-info: $(DESTDIR)$(infodir)/gnat_ugn.info \ $(DESTDIR)$(infodir)/gnat_rm.info \ $(DESTDIR)$(infodir)/gnat-style.info -$(DESTDIR)$(infodir)/gnat_ugn.info: doc/gnat_ugn/info/texinfo/gnat_ugn.info installdirs - -rm -f $@ - -$(INSTALL_DATA) $< $@ +ADA_DVIFILES = doc/gnat_ugn.dvi \ + doc/gnat_rm.dvi doc/gnat-style.dvi -$(DESTDIR)$(infodir)/gnat_rm.info: doc/gnat_rm/info/texinfo/gnat_rm.info installdirs - -rm -f $@ - -$(INSTALL_DATA) $< $@ +ada.dvi: $(ADA_DVIFILES) -$(DESTDIR)$(infodir)/gnat-style.info: doc/gnat-style/info/texinfo/gnat-style.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 -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_PDFFILES = doc/gnat_ugn.pdf \ + doc/gnat_rm.pdf doc/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" @@ -873,18 +874,33 @@ ada.install-pdf: $(ADA_PDFFILES) $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/gcc/$$f"; \ done -ada.html: doc/gnat_ugn/html/html/index.html doc/gnat_rm/html/html/index.html doc/gnat-style/html/html/index.html +ada.html: -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 +ada.install-html: -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.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-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.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 $@ $< -ada.install-html: +doc/gnat-style.dvi: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi + $(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $< + +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_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 $@ $< # Install hooks: # gnat1 is installed elsewhere as part of $(COMPILERS). diff --git a/gcc/ada/gnat-style.texi b/gcc/ada/gnat-style.texi new file mode 100644 index 000000000000..f3b1c29a24f0 --- /dev/null +++ b/gcc/ada/gnat-style.texi @@ -0,0 +1,1437 @@ +\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 new file mode 100644 index 000000000000..fbd8bb8d6b29 --- /dev/null +++ b/gcc/ada/gnat_rm.texi @@ -0,0 +1,30385 @@ +\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 ”. 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 => ) | + (F1 => , 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 “ .. <>”. 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 ; +@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 : ) 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 : ) 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 : ) 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 ”, where +“” 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 ( : in out System.Address) returns Integer +is + -- ... +begin + <__strub_update> (); -- Updates the stack WaterMark. + -- ... +end; +@end example + +whereas its callers are modified from: + +@example +X := Foo; +@end example + +to: + +@example +declare + : System.Address; +begin + <__strub_enter> (); -- Initialize . + X := Foo (); + <__strub_leave> (); -- Scrubs stack up to . +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 + : System.Address; + procedure Strubbed_Bar ( : in out System.Address) is + begin + <__strub_update> (); -- Updates the stack WaterMark. + -- original Bar body. + end Strubbed_Bar; +begin + <__strub_enter> (); -- Initialize . + Strubbed_Bar (); + <__strub_leave> (); -- Scrubs stack up to . +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 new file mode 100644 index 000000000000..7b1aaeba9545 --- /dev/null +++ b/gcc/ada/gnat_ugn.texi @@ -0,0 +1,29389 @@ +\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 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 .gpr, a backup copy of the project file is created +in the project directory with file name .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 [then] + lines +#elsif [then] + lines +#elsif [then] + lines +... +#else + lines +#end if; +@end example + +In this example, is defined by the following grammar: + +@example + ::= + ::= = "" + ::= = + ::= = + ::= > + ::= >= + ::= < + ::= <= + ::= 'Defined + ::= not + ::= and + ::= or + ::= and then + ::= or else + ::= ( ) +@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 ( ::= ) 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 ( ::= ’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 + ::= + [ ] @{ @} + + ::= | '*' + + ::= + + := + + := (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 + +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 + +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 +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 +#include +@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 [] [] [] +@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 +`/$rts_path' + +@item +`/$rts_path' + +@item +`/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] +@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 ( [, ]) +pragma Debug () +pragma Type_Invariant (, ) +pragma Predicate (, ) +pragma Precondition (, ) +pragma Postcondition (, ) +@end example + +The aspects have the form: + +@example +with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate] + => ; +@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 -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: + + ../ + /home/comar/local/adainclude/ + +Object Search Path: + + ../ + /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/ + +Project Search Path: + + /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 + + + + + + + + + + + + + + + + + +@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" /bin/gdb +@end example +@end quotation + +where “gdb-cert” should be replaced by the actual certificate +name chosen above, and 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