From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1851) id 75CC7383235B; Mon, 14 Nov 2022 08:39:08 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 75CC7383235B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1668415148; bh=MvGG93aPb2H1BeAnt614tZmvL0BcWdt3Tu5EqHLwgVo=; h=From:To:Subject:Date:From; b=d6EmFVKqQtQrJOBNbChxD2hG+IQNiTtWZz94bUosW9bl9VAooyahjD7EnNhOuY1kq 5gOQvxLzrcAGcRSHeAwl7Z/CVKUN3MNRZagjxLKJRLmE3HdTcuQcTKCxqlBzBIgYwI 9U6xPBBupc3/ooJoSxgfR8E4QC3h2HzbtS8+TeJs= MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="utf-8" From: Martin Liska To: gcc-cvs@gcc.gnu.org Subject: [gcc r13-3991] Revert "sphinx: ada: port to Sphinx" X-Act-Checkin: gcc X-Git-Author: Martin Liska X-Git-Refname: refs/heads/master X-Git-Oldrev: b4c839e7255cc6108a9a22146f064b740a5710ca X-Git-Newrev: 64d5610f44c995b88261bf83f53a200355cb530f Message-Id: <20221114083908.75CC7383235B@sourceware.org> Date: Mon, 14 Nov 2022 08:39:08 +0000 (GMT) List-Id: https://gcc.gnu.org/g:64d5610f44c995b88261bf83f53a200355cb530f commit r13-3991-g64d5610f44c995b88261bf83f53a200355cb530f Author: Martin Liska Date: Sun Nov 13 21:59:18 2022 +0100 Revert "sphinx: ada: port to Sphinx" This reverts commit 0a543515957ff47feba739e6f71062fb2fb99125. Diff: --- gcc/ada/doc/Makefile | 87 + .../doc/{gnat-style/index.rst => gnat-style.rst} | 2 +- gcc/ada/doc/gnat-style/conf.py | 26 - .../gnat-style/gnu_free_documentation_license.rst | 1 - gcc/ada/doc/{gnat_rm/index.rst => gnat_rm.rst} | 40 +- gcc/ada/doc/gnat_rm/conf.py | 26 - .../doc/gnat_rm/gnu_free_documentation_license.rst | 1 - .../doc/gnat_rm/security_hardening_features.rst | 2 - gcc/ada/doc/{gnat_ugn/index.rst => gnat_ugn.rst} | 22 +- gcc/ada/doc/gnat_ugn/conf.py | 26 - .../gnat_ugn/gnu_free_documentation_license.rst | 1 - .../doc/gnat_ugn/platform_specific_information.rst | 6 + gcc/ada/doc/share/adabaseconf.py | 81 - gcc/ada/doc/share/conf.py | 148 + .../doc/share/gnu_free_documentation_license.rst | 458 + .../{ada_latex_elements.py => latex_elements.py} | 11 +- gcc/ada/gcc-interface/Make-lang.in | 98 +- gcc/ada/gnat-style.texi | 1437 + gcc/ada/gnat_rm.texi | 30385 +++++++++++++++++++ gcc/ada/gnat_ugn.texi | 29389 ++++++++++++++++++ 20 files changed, 62000 insertions(+), 247 deletions(-) diff --git a/gcc/ada/doc/Makefile b/gcc/ada/doc/Makefile new file mode 100644 index 00000000000..4adfd368cc8 --- /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 b9428749f1f..527e7ba2a66 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 a413d2632eb..00000000000 --- 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 33c62cf7fde..00000000000 --- 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 6c2616a0f1c..7743ef8b5f4 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 e99d1e6bd13..00000000000 --- 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 33c62cf7fde..00000000000 --- 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 5a1f2d46326..d7c02b94f36 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 d3d1dac3569..0ac68763760 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 94e3c07e836..00000000000 --- 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 33c62cf7fde..00000000000 --- 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 3ada65ddade..4d25dea3d1e 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 4a80a838c63..00000000000 --- 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 00000000000..bb36bfa0c6a --- /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 00000000000..0235545155f --- /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 9578c0296af..f23b2aff6be 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 71a26e52627..45a4168e890 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 00000000000..f3b1c29a24f --- /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 00000000000..fbd8bb8d6b2 --- /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 a[...] [diff truncated at 524288 bytes]