From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1851) id BB0183858426; Tue, 8 Nov 2022 10:21:18 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org BB0183858426 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1667902878; bh=Ywk1mVOwDai1VqIzlvRBE6s90qTcSGClJr55H7A1fF4=; h=From:To:Subject:Date:From; b=eRGGtSsr96Q2Hox8KkmUCqy2Z4FSH9sCkkAeLa8ZviYKyYTIU7P/k591KI7rxguT/ cMSR+FpWUidLtdHPzO7ViGDIgMJsdBGSvxw2s/e81GN6nxDdiQu+aKyCgGj6kgMHoz A5bVBrR/649QOrI/vlwt4c1TNPZ6JCH2QBvGE8gY= 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(refs/users/marxin/heads/sphinx-final)] sphinx: ada: port to Sphinx X-Act-Checkin: gcc X-Git-Author: Martin Liska X-Git-Refname: refs/users/marxin/heads/sphinx-final X-Git-Oldrev: b49880e59c74af45efd9a122ebb247add8b4dae9 X-Git-Newrev: 4c30c0e5af32e5b2ee943eaec43ca99d53e51db6 Message-Id: <20221108102118.BB0183858426@sourceware.org> Date: Tue, 8 Nov 2022 10:21:18 +0000 (GMT) List-Id: https://gcc.gnu.org/g:4c30c0e5af32e5b2ee943eaec43ca99d53e51db6 commit 4c30c0e5af32e5b2ee943eaec43ca99d53e51db6 Author: Martin Liska Date: Mon Jun 28 13:53:49 2021 +0200 sphinx: ada: port to Sphinx gcc/ada/ChangeLog: * doc/gnat-style.rst: Moved to... * doc/gnat-style/index.rst: ...here. * doc/gnat_rm.rst: Moved to... * doc/gnat_rm/index.rst: ...here. * doc/gnat_ugn.rst: Moved to... * doc/gnat_ugn/index.rst: ...here. * doc/share/latex_elements.py: Moved to... * doc/share/ada_latex_elements.py: ...here. * gcc-interface/Make-lang.in: * doc/Makefile: Removed. * doc/share/conf.py: Removed. * doc/share/gnu_free_documentation_license.rst: Removed. * gnat-style.texi: Removed. * gnat_rm.texi: Removed. * gnat_ugn.texi: Removed. * doc/gnat-style/conf.py: New file. * doc/gnat-style/gnu_free_documentation_license.rst: New file. * doc/gnat_rm/conf.py: New file. * doc/gnat_rm/gnu_free_documentation_license.rst: New file. * doc/gnat_ugn/conf.py: New file. * doc/gnat_ugn/gnu_free_documentation_license.rst: New file. * doc/share/adabaseconf.py: New file. * doc/gnat_rm/security_hardening_features.rst: Add role. * doc/gnat_ugn/platform_specific_information.rst: Remove duplicate definition of |nbsp|. Diff: --- gcc/ada/doc/Makefile | 87 - gcc/ada/doc/gnat-style/conf.py | 26 + .../gnat-style/gnu_free_documentation_license.rst | 1 + .../doc/{gnat-style.rst => gnat-style/index.rst} | 2 +- gcc/ada/doc/gnat_rm/conf.py | 26 + .../doc/gnat_rm/gnu_free_documentation_license.rst | 1 + gcc/ada/doc/{gnat_rm.rst => gnat_rm/index.rst} | 40 +- .../doc/gnat_rm/security_hardening_features.rst | 2 + gcc/ada/doc/gnat_ugn/conf.py | 26 + .../gnat_ugn/gnu_free_documentation_license.rst | 1 + gcc/ada/doc/{gnat_ugn.rst => gnat_ugn/index.rst} | 22 +- .../doc/gnat_ugn/platform_specific_information.rst | 6 - .../{latex_elements.py => ada_latex_elements.py} | 11 +- gcc/ada/doc/share/adabaseconf.py | 81 + gcc/ada/doc/share/conf.py | 148 - .../doc/share/gnu_free_documentation_license.rst | 458 - 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, 247 insertions(+), 62000 deletions(-) diff --git a/gcc/ada/doc/Makefile b/gcc/ada/doc/Makefile deleted file mode 100644 index 4adfd368cc8..00000000000 --- a/gcc/ada/doc/Makefile +++ /dev/null @@ -1,87 +0,0 @@ -# Makefile for Sphinx documentation - -# You can set these variables from the command line. -SPHINXOPTS = -W -SPHINXBUILD = DOC_NAME=$* sphinx-build -PAPER = -BUILDDIR = build -SOURCEDIR = . - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) \ - -c $(SOURCEDIR)/share \ - -d $(BUILDDIR)/$*/doctrees \ - $(SOURCEDIR) -DOC_LIST=gnat_rm gnat_ugn gnat-style -FMT_LIST=html pdf txt info - -.PHONY: help clean - -help: - @echo "Please use \`make ' 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/conf.py b/gcc/ada/doc/gnat-style/conf.py new file mode 100644 index 00000000000..a413d2632eb --- /dev/null +++ b/gcc/ada/doc/gnat-style/conf.py @@ -0,0 +1,26 @@ +# Configuration file for the Sphinx documentation builder. + +import sys +sys.path.append('../share') + +from adabaseconf import * + +name = 'gnat-style' +project = 'GNAT Coding Style: A Guide for GNAT Developers' +authors = 'AdaCore' + +set_latex_elements(latex_elements, project) + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +latex_documents = [ + ('index', f'{name}.tex', project, authors, 'manual'), +] + +texinfo_documents = [ + ('index', name, project, authors, None, None, None, True) +] + +tags.add(get_gnat_build_type()) +set_common(name, globals()) diff --git a/gcc/ada/doc/gnat-style/gnu_free_documentation_license.rst b/gcc/ada/doc/gnat-style/gnu_free_documentation_license.rst new file mode 100644 index 00000000000..33c62cf7fde --- /dev/null +++ b/gcc/ada/doc/gnat-style/gnu_free_documentation_license.rst @@ -0,0 +1 @@ +.. include:: ../../../../doc/gnu_free_documentation_license.rst diff --git a/gcc/ada/doc/gnat-style.rst b/gcc/ada/doc/gnat-style/index.rst similarity index 99% rename from gcc/ada/doc/gnat-style.rst rename to gcc/ada/doc/gnat-style/index.rst index 527e7ba2a66..b9428749f1f 100644 --- a/gcc/ada/doc/gnat-style.rst +++ b/gcc/ada/doc/gnat-style/index.rst @@ -688,4 +688,4 @@ Program Structure and Compilation Issues .. index:: krunch.ads file .. toctree:: - share/gnu_free_documentation_license + gnu_free_documentation_license diff --git a/gcc/ada/doc/gnat_rm/conf.py b/gcc/ada/doc/gnat_rm/conf.py new file mode 100644 index 00000000000..e99d1e6bd13 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/conf.py @@ -0,0 +1,26 @@ +# Configuration file for the Sphinx documentation builder. + +import sys +sys.path.append('../share') + +from adabaseconf import * + +name = 'gnat_rm' +project = 'GNAT Reference Manual' +authors = 'AdaCore' + +set_latex_elements(latex_elements, project) + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +latex_documents = [ + ('index', f'{name}.tex', project, authors, 'manual'), +] + +texinfo_documents = [ + ('index', name, project, authors, None, None, None, True) +] + +tags.add(get_gnat_build_type()) +set_common(name, globals()) diff --git a/gcc/ada/doc/gnat_rm/gnu_free_documentation_license.rst b/gcc/ada/doc/gnat_rm/gnu_free_documentation_license.rst new file mode 100644 index 00000000000..33c62cf7fde --- /dev/null +++ b/gcc/ada/doc/gnat_rm/gnu_free_documentation_license.rst @@ -0,0 +1 @@ +.. include:: ../../../../doc/gnu_free_documentation_license.rst diff --git a/gcc/ada/doc/gnat_rm.rst b/gcc/ada/doc/gnat_rm/index.rst similarity index 54% rename from gcc/ada/doc/gnat_rm.rst rename to gcc/ada/doc/gnat_rm/index.rst index 7743ef8b5f4..6c2616a0f1c 100644 --- a/gcc/ada/doc/gnat_rm.rst +++ b/gcc/ada/doc/gnat_rm/index.rst @@ -39,25 +39,25 @@ GNAT Reference Manual :numbered: :maxdepth: 3 - gnat_rm/about_this_guide - gnat_rm/implementation_defined_pragmas - gnat_rm/implementation_defined_aspects - gnat_rm/implementation_defined_attributes - gnat_rm/standard_and_implementation_defined_restrictions - gnat_rm/implementation_advice - gnat_rm/implementation_defined_characteristics - gnat_rm/intrinsic_subprograms - gnat_rm/representation_clauses_and_pragmas - gnat_rm/standard_library_routines - gnat_rm/the_implementation_of_standard_i_o - gnat_rm/the_gnat_library - gnat_rm/interfacing_to_other_languages - gnat_rm/specialized_needs_annexes - gnat_rm/implementation_of_specific_ada_features - gnat_rm/implementation_of_ada_2012_features - gnat_rm/security_hardening_features - gnat_rm/obsolescent_features - gnat_rm/compatibility_and_porting_guide + about_this_guide + implementation_defined_pragmas + implementation_defined_aspects + implementation_defined_attributes + standard_and_implementation_defined_restrictions + implementation_advice + implementation_defined_characteristics + intrinsic_subprograms + representation_clauses_and_pragmas + standard_library_routines + the_implementation_of_standard_i_o + the_gnat_library + interfacing_to_other_languages + specialized_needs_annexes + implementation_of_specific_ada_features + implementation_of_ada_2012_features + security_hardening_features + obsolescent_features + compatibility_and_porting_guide .. raw:: latex @@ -66,4 +66,4 @@ GNAT Reference Manual .. toctree:: :maxdepth: 3 - share/gnu_free_documentation_license + gnu_free_documentation_license diff --git a/gcc/ada/doc/gnat_rm/security_hardening_features.rst b/gcc/ada/doc/gnat_rm/security_hardening_features.rst index d7c02b94f36..5a1f2d46326 100644 --- a/gcc/ada/doc/gnat_rm/security_hardening_features.rst +++ b/gcc/ada/doc/gnat_rm/security_hardening_features.rst @@ -1,3 +1,5 @@ +.. role:: switch(samp) + .. _Security_Hardening_Features: *************************** diff --git a/gcc/ada/doc/gnat_ugn/conf.py b/gcc/ada/doc/gnat_ugn/conf.py new file mode 100644 index 00000000000..94e3c07e836 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/conf.py @@ -0,0 +1,26 @@ +# Configuration file for the Sphinx documentation builder. + +import sys +sys.path.append('../share') + +from adabaseconf import * + +name = 'gnat_ugn' +project = "GNAT User's Guide for Native Platforms" +authors = 'AdaCore' + +set_latex_elements(latex_elements, project) + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +latex_documents = [ + ('index', f'{name}.tex', project, authors, 'manual'), +] + +texinfo_documents = [ + ('index', name, project, authors, None, None, None, True) +] + +tags.add(get_gnat_build_type()) +set_common(name, globals()) diff --git a/gcc/ada/doc/gnat_ugn/gnu_free_documentation_license.rst b/gcc/ada/doc/gnat_ugn/gnu_free_documentation_license.rst new file mode 100644 index 00000000000..33c62cf7fde --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/gnu_free_documentation_license.rst @@ -0,0 +1 @@ +.. include:: ../../../../doc/gnu_free_documentation_license.rst diff --git a/gcc/ada/doc/gnat_ugn.rst b/gcc/ada/doc/gnat_ugn/index.rst similarity index 63% rename from gcc/ada/doc/gnat_ugn.rst rename to gcc/ada/doc/gnat_ugn/index.rst index 0ac68763760..d3d1dac3569 100644 --- a/gcc/ada/doc/gnat_ugn.rst +++ b/gcc/ada/doc/gnat_ugn/index.rst @@ -40,12 +40,12 @@ GNAT User's Guide for Native Platforms :maxdepth: 3 :numbered: - gnat_ugn/about_this_guide - gnat_ugn/getting_started_with_gnat - gnat_ugn/the_gnat_compilation_model - gnat_ugn/building_executable_programs_with_gnat - gnat_ugn/gnat_utility_programs - gnat_ugn/gnat_and_program_execution + about_this_guide + getting_started_with_gnat + the_gnat_compilation_model + building_executable_programs_with_gnat + gnat_utility_programs + gnat_and_program_execution .. raw:: latex @@ -54,10 +54,10 @@ GNAT User's Guide for Native Platforms .. toctree:: :maxdepth: 3 - A. Platform-Specific Information - 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/platform_specific_information.rst b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst index 4d25dea3d1e..3ada65ddade 100644 --- a/gcc/ada/doc/gnat_ugn/platform_specific_information.rst +++ b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst @@ -1,11 +1,5 @@ .. role:: switch(samp) -.. -- Non-breaking space in running text - -- E.g. Ada |nbsp| 95 - -.. |nbsp| unicode:: 0xA0 - :trim: - .. _Platform_Specific_Information: ***************************** diff --git a/gcc/ada/doc/share/latex_elements.py b/gcc/ada/doc/share/ada_latex_elements.py similarity index 87% rename from gcc/ada/doc/share/latex_elements.py rename to gcc/ada/doc/share/ada_latex_elements.py index f23b2aff6be..9578c0296af 100644 --- a/gcc/ada/doc/share/latex_elements.py +++ b/gcc/ada/doc/share/ada_latex_elements.py @@ -1,5 +1,9 @@ # define some latex elements to be used for PDF output +import os + +folder = os.path.dirname(os.path.realpath(__file__)) + PAGE_BLANK = r''' \makeatletter \def\cleartooddpage{%% @@ -46,7 +50,7 @@ TOC_CMD = r''' \makeatother ''' -with open('copyright.tex', 'r') as fd: +with open(os.path.join(folder, 'copyright.tex'), 'r') as fd: copyright = fd.read() TOC = r''' @@ -62,6 +66,11 @@ LATEX_HYPHEN = r''' \tolerance=1000 ''' +ENCLOSE = r''' +@definfoenclose strong,*,* +@definfoenclose emph,',' +''' + def doc_settings(full_document_name, version): return '\n'.join([ diff --git a/gcc/ada/doc/share/adabaseconf.py b/gcc/ada/doc/share/adabaseconf.py new file mode 100644 index 00000000000..4a80a838c63 --- /dev/null +++ b/gcc/ada/doc/share/adabaseconf.py @@ -0,0 +1,81 @@ +# GNAT build configuration file + +import sys +sys.path.append('.') +sys.path.append('../../../../doc') + +from baseconf import * + +import os +import re +import sys +import time + +import ada_latex_elements + +import ada_pygments + +gnatvsn_content = read_file('ada/gnatvsn.ads') + + +def get_gnat_version(): + m = re.search(r'Gnat_Static_Version_String : ' + + r'constant String := "([^\(\)]+)\(.*\)?";', + gnatvsn_content) + if m: + return m.group(1).strip() + else: + return gcc_BASEVER + + +def get_gnat_build_type(): + m = re.search(r'Build_Type : constant Gnat_Build_Type := (.+);', + gnatvsn_content) + if m: + return {'Gnatpro': 'PRO', + 'FSF': 'FSF', + 'GPL': 'GPL'}[m.group(1).strip()] + else: + print('cannot compute GNAT build type') + sys.exit(1) + + +copyright = '2008-%s, Free Software Foundation' % YEAR + +version = get_gnat_version() +release = get_gnat_version() + +if os.path.isfile('adacore_transparent.png'): + html_logo = 'adacore_transparent.png' +if os.path.isfile('favicon.ico'): + html_favicon = 'favicon.ico' + +latex_additional_files = ['../share/gnat.sty'] + +copyright_macros = { + 'date': time.strftime('%b %d, %Y'), + 'edition': 'GNAT %s Edition' % 'Pro' if get_gnat_build_type() == 'PRO' + else 'GPL', + 'name': 'GNU Ada', + 'tool': 'GNAT', + 'version': version} + + +def set_latex_elements(latex_elements, title): + elements = { + 'preamble': '\\usepackage{gnat}\n' + + ada_latex_elements.TOC_DEPTH + + ada_latex_elements.PAGE_BLANK + + ada_latex_elements.TOC_CMD + + ada_latex_elements.LATEX_HYPHEN + + ada_latex_elements.doc_settings(title, get_gnat_version()), + 'tableofcontents': ada_latex_elements.TOC % copyright_macros + } + for key, value in elements.items(): + latex_elements.setdefault(key, '') + latex_elements[key] += value + + +def setup(app): + app.add_lexer('ada', ada_pygments.AdaLexer) + app.add_lexer('gpr', ada_pygments.GNATProjectLexer) diff --git a/gcc/ada/doc/share/conf.py b/gcc/ada/doc/share/conf.py deleted file mode 100644 index bb36bfa0c6a..00000000000 --- a/gcc/ada/doc/share/conf.py +++ /dev/null @@ -1,148 +0,0 @@ -# -*- coding: utf-8 -*- -# Style_Check:Python_Fragment (meaning no pyflakes check) -# -# GNAT build configuration file - -import sys -import os -import time -import re - -sys.path.append('.') - -import ada_pygments -import latex_elements - -# Some configuration values for the various documentation handled by -# this conf.py - -DOCS = { - 'gnat_rm': { - 'title': 'GNAT Reference Manual'}, - 'gnat_ugn': { - 'title': 'GNAT User\'s Guide for Native Platforms'}, - 'gnat-style': { - 'title': 'GNAT Coding Style: A Guide for GNAT Developers'}} - -# Then retrieve the source directory -root_source_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) -gnatvsn_spec = os.path.join(root_source_dir, '..', 'gnatvsn.ads') -basever = os.path.join(root_source_dir, '..', '..', 'BASE-VER') -texi_fsf = True # Set to False when FSF doc is switched to sphinx by default - -with open(gnatvsn_spec, 'r') as fd: - gnatvsn_content = fd.read() - - -def get_copyright(): - return '2008-%s, Free Software Foundation' % time.strftime('%Y') - - -def get_gnat_version(): - m = re.search(r'Gnat_Static_Version_String : ' + - r'constant String := "([^\(\)]+)\(.*\)?";', - gnatvsn_content) - if m: - return m.group(1).strip() - else: - if texi_fsf and os.path.exists(basever): - return '' - - try: - with open(basever) as fd: - return fd.read() - except Exception: - pass - - print('cannot find GNAT version in gnatvsn.ads or in ' + basever) - sys.exit(1) - - -def get_gnat_build_type(): - m = re.search(r'Build_Type : constant Gnat_Build_Type := (.+);', - gnatvsn_content) - if m: - return {'Gnatpro': 'PRO', - 'FSF': 'FSF', - 'GPL': 'GPL'}[m.group(1).strip()] - else: - print('cannot compute GNAT build type') - sys.exit(1) - - -# First retrieve the name of the documentation we are building -doc_name = os.environ.get('DOC_NAME', None) -if doc_name is None: - print('DOC_NAME environment variable should be set') - sys.exit(1) - -if doc_name not in DOCS: - print('%s is not a valid documentation name' % doc_name) - sys.exit(1) - - -# Exclude sources that are not part of the current documentation -exclude_patterns = [] -for d in os.listdir(root_source_dir): - if d not in ('share', doc_name, doc_name + '.rst'): - exclude_patterns.append(d) - print('ignoring %s' % d) - -if doc_name == 'gnat_rm': - exclude_patterns.append('share/gnat_project_manager.rst') - print('ignoring share/gnat_project_manager.rst') - -extensions = [] -templates_path = ['_templates'] -source_suffix = '.rst' -master_doc = doc_name - -# General information about the project. -project = DOCS[doc_name]['title'] - -copyright = get_copyright() - -version = get_gnat_version() -release = get_gnat_version() - -pygments_style = None -tags.add(get_gnat_build_type()) -html_theme = 'sphinxdoc' -if os.path.isfile('adacore_transparent.png'): - html_logo = 'adacore_transparent.png' -if os.path.isfile('favicon.ico'): - html_favicon = 'favicon.ico' - -html_static_path = ['_static'] - -latex_additional_files = ['gnat.sty'] - -copyright_macros = { - 'date': time.strftime("%b %d, %Y"), - 'edition': 'GNAT %s Edition' % 'Pro' if get_gnat_build_type() == 'PRO' - else 'GPL', - 'name': 'GNU Ada', - 'tool': 'GNAT', - 'version': version} - -latex_elements = { - 'preamble': '\\usepackage{gnat}\n' + - latex_elements.TOC_DEPTH + - latex_elements.PAGE_BLANK + - latex_elements.TOC_CMD + - latex_elements.LATEX_HYPHEN + - latex_elements.doc_settings(DOCS[doc_name]['title'], - get_gnat_version()), - 'tableofcontents': latex_elements.TOC % copyright_macros} - -latex_documents = [ - (master_doc, '%s.tex' % doc_name, project, 'AdaCore', 'manual')] - -texinfo_documents = [ - (master_doc, doc_name, project, - 'AdaCore', doc_name, doc_name, '')] - - -def setup(app): - app.add_lexer('ada', ada_pygments.AdaLexer) - app.add_lexer('gpr', ada_pygments.GNATProjectLexer) diff --git a/gcc/ada/doc/share/gnu_free_documentation_license.rst b/gcc/ada/doc/share/gnu_free_documentation_license.rst deleted file mode 100644 index 0235545155f..00000000000 --- a/gcc/ada/doc/share/gnu_free_documentation_license.rst +++ /dev/null @@ -1,458 +0,0 @@ -.. _gnu_fdl: - -****************************** -GNU Free Documentation License -****************************** - -Version 1.3, 3 November 2008 - -Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc -https://fsf.org/ - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -**Preamble** - -The purpose of this License is to make a manual, textbook, or other -functional and useful document "free" in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of "copyleft", which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -**1. APPLICABILITY AND DEFINITIONS** - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The **Document**, below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as "**you**". You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A "**Modified Version**" of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A "**Secondary Section**" is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The "**Invariant Sections**" are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The "**Cover Texts**" are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A "**Transparent**" copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not "Transparent" is called **Opaque**. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The "**Title Page**" means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, "Title Page" means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The "**publisher**" means any person or entity that distributes -copies of the Document to the public. - -A section "**Entitled XYZ**" means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as "**Acknowledgements**", -"**Dedications**", "**Endorsements**", or "**History**".) -To "**Preserve the Title**" -of such a section when you modify the Document means that it remains a -section "Entitled XYZ" according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -**2. VERBATIM COPYING** - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -**3. COPYING IN QUANTITY** - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -**4. MODIFICATIONS** - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -A. Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission. - -B. List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has fewer than five), - unless they release you from this requirement. - -C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - -D. Preserve all the copyright notices of the Document. - -E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - -F. Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below. - -G. Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice. -H. Include an unaltered copy of this License. - -I. Preserve the section Entitled "History", Preserve its Title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section Entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - -J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. - -K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the section all - the substance and tone of each of the contributor acknowledgements - and/or dedications given therein. - -L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles. - -M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - -N. Do not retitle any existing section to be Entitled "Endorsements" - or to conflict in title with any Invariant Section. - -O. Preserve any Warranty Disclaimers. - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled "Endorsements", provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -**5. COMBINING DOCUMENTS** - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled "History" -in the various original documents, forming one section Entitled -"History"; likewise combine any sections Entitled "Acknowledgements", -and any sections Entitled "Dedications". You must delete all sections -Entitled "Endorsements". - -**6. COLLECTIONS OF DOCUMENTS** - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -**7. AGGREGATION WITH INDEPENDENT WORKS** - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an "aggregate" if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -**8. TRANSLATION** - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled "Acknowledgements", -"Dedications", or "History", the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -**9. TERMINATION** - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -**10. FUTURE REVISIONS OF THIS LICENSE** - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -https://www.gnu.org/copyleft/. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License "or any later version" applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -**11. RELICENSING** - -"Massive Multiauthor Collaboration Site" (or "MMC Site") means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -"Massive Multiauthor Collaboration" (or "MMC") contained in the -site means any set of copyrightable works thus published on the MMC -site. - -"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -"Incorporate" means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is "eligible for relicensing" if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -**ADDENDUM: How to use this License for your documents** - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - - Copyright © YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled "GNU - Free Documentation License". - - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the "with ... Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. diff --git a/gcc/ada/gcc-interface/Make-lang.in b/gcc/ada/gcc-interface/Make-lang.in index 02b2d1c6f2a..f91b8c63a60 100644 --- a/gcc/ada/gcc-interface/Make-lang.in +++ b/gcc/ada/gcc-interface/Make-lang.in @@ -808,32 +808,24 @@ ada.tags: force # Generate documentation. -doc/gnat_ugn.info: ada/gnat_ugn.texi \ - $(gcc_docdir)/include/fdl.texi $(gcc_docdir)/include/gcc-common.texi \ - gcc-vers.texi - if [ x$(BUILD_INFO) = xinfo ]; then \ - rm -f $(@)*; \ - $(MAKEINFO) $(MAKEINFOFLAGS) -I$(gcc_docdir)/include \ - -I$(srcdir)/ada -o $@ $<; \ +doc/gnat_ugn/info/texinfo/gnat_ugn.info: $(SPHINX_FILES) + + if [ x$(SPHINX_BUILD) = xsphinx-build ]; then \ + make -C $(srcdir)/../doc info SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_ugn BUILDDIR=$(objdir)/doc/gnat_ugn/info; \ else true; fi -doc/gnat_rm.info: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - if [ x$(BUILD_INFO) = xinfo ]; then \ - rm -f $(@)*; \ - $(MAKEINFO) $(MAKEINFOFLAGS) -I$(gcc_docdir)/include \ - -I$(srcdir)/ada -o $@ $<; \ +doc/gnat_rm/info/texinfo/gnat_rm.info: $(SPHINX_FILES) + + if [ x$(SPHINX_BUILD) = xsphinx-build ]; then \ + make -C $(srcdir)/../doc info SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_rm BUILDDIR=$(objdir)/doc/gnat_rm/info; \ else true; fi -doc/gnat-style.info: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - if [ x$(BUILD_INFO) = xinfo ]; then \ - rm -f $(@)*; \ - $(MAKEINFO) $(MAKEINFOFLAGS) -I$(gcc_docdir)/include \ - -I$(srcdir)/ada -o $@ $<; \ +doc/gnat-style/info/texinfo/gnat-style.info: $(SPHINX_FILES) + + if [ x$(SPHINX_BUILD) = xsphinx-build ]; then \ + make -C $(srcdir)/../doc info SOURCEDIR=$(abs_srcdir)/ada/doc/gnat-style BUILDDIR=$(objdir)/doc/gnat-style/info; \ else true; fi -ADA_INFOFILES = doc/gnat_ugn.info doc/gnat_rm.info doc/gnat-style.info +ADA_INFOFILES = doc/gnat_ugn/info/texinfo/gnat_ugn.info \ + doc/gnat_rm/info/texinfo/gnat_rm.info \ + doc/gnat-style/info/texinfo/gnat-style.info ada.info: $(ADA_INFOFILES) @@ -844,26 +836,33 @@ ada.install-info: $(DESTDIR)$(infodir)/gnat_ugn.info \ $(DESTDIR)$(infodir)/gnat_rm.info \ $(DESTDIR)$(infodir)/gnat-style.info -ADA_DVIFILES = doc/gnat_ugn.dvi \ - doc/gnat_rm.dvi doc/gnat-style.dvi +$(DESTDIR)$(infodir)/gnat_ugn.info: doc/gnat_ugn/info/texinfo/gnat_ugn.info installdirs + -rm -f $@ + -$(INSTALL_DATA) $< $@ -ada.dvi: $(ADA_DVIFILES) +$(DESTDIR)$(infodir)/gnat_rm.info: doc/gnat_rm/info/texinfo/gnat_rm.info installdirs + -rm -f $@ + -$(INSTALL_DATA) $< $@ -ada.install-dvi: $(ADA_DVIFILES) - @$(NORMAL_INSTALL) - test -z "$(dvidir)/gcc" || $(mkinstalldirs) "$(DESTDIR)$(dvidir)/gcc" - @list='$(ADA_DVIFILES)'; for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(dvi__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/gcc/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/gcc/$$f"; \ - done +$(DESTDIR)$(infodir)/gnat-style.info: doc/gnat-style/info/texinfo/gnat-style.info installdirs + -rm -f $@ + -$(INSTALL_DATA) $< $@ -ADA_PDFFILES = doc/gnat_ugn.pdf \ - doc/gnat_rm.pdf doc/gnat-style.pdf +ADA_PDFFILES = doc/gnat_ugn/pdf/latex/gnat_ugn.pdf\ + doc/gnat_rm/pdf/latex/gnat_rm.pdf \ + doc/gnat-style/pdf/latex/gnat-style.pdf ada.pdf: $(ADA_PDFFILES) +doc/gnat_ugn/pdf/latex/gnat_ugn.pdf: $(SPHINX_FILES) + + make -C $(srcdir)/../doc latexpdf SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_ugn BUILDDIR=$(objdir)/doc/gnat_ugn/pdf + +doc/gnat_rm/pdf/latex/gnat_rm.pdf: $(SPHINX_FILES) + + make -C $(srcdir)/../doc latexpdf SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_rm BUILDDIR=$(objdir)/doc/gnat_rm/pdf + +doc/gnat-style/pdf/latex/gnat-style.pdf: $(SPHINX_FILES) + + make -C $(srcdir)/../doc latexpdf SOURCEDIR=$(abs_srcdir)/ada/doc/gnat-style BUILDDIR=$(objdir)/doc/gnat-style/pdf + ada.install-pdf: $(ADA_PDFFILES) @$(NORMAL_INSTALL) test -z "$(pdfdir)/gcc" || $(mkinstalldirs) "$(DESTDIR)$(pdfdir)/gcc" @@ -874,33 +873,18 @@ ada.install-pdf: $(ADA_PDFFILES) $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/gcc/$$f"; \ done -ada.html: +ada.html: doc/gnat_ugn/html/html/index.html doc/gnat_rm/html/html/index.html doc/gnat-style/html/html/index.html -ada.install-html: - -doc/gnat_ugn.dvi: ada/gnat_ugn.texi \ - $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - $(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $< - -doc/gnat_rm.dvi: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - $(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $< +doc/gnat_ugn/html/html/index.html: $(SPHINX_FILES) + + make -C $(srcdir)/../doc html SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_ugn BUILDDIR=$(objdir)/doc/gnat_ugn/html -doc/gnat-style.dvi: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi - $(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $< +doc/gnat_rm/html/html/index.html: $(SPHINX_FILES) + + make -C $(srcdir)/../doc html SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_rm BUILDDIR=$(objdir)/doc/gnat_rm/html -doc/gnat_ugn.pdf: ada/gnat_ugn.texi \ - $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - $(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $< +doc/gnat-style/html/html/index.html: $(SPHINX_FILES) + + make -C $(srcdir)/../doc html SOURCEDIR=$(abs_srcdir)/ada/doc/gnat-style BUILDDIR=$(objdir)/doc/gnat-style/html -doc/gnat_rm.pdf: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - $(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $< - -doc/gnat-style.pdf: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi - $(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $< +ada.install-html: # Install hooks: # gnat1 is installed elsewhere as part of $(COMPILERS). diff --git a/gcc/ada/gnat-style.texi b/gcc/ada/gnat-style.texi deleted file mode 100644 index f3b1c29a24f..00000000000 --- a/gcc/ada/gnat-style.texi +++ /dev/null @@ -1,1437 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename gnat-style.info -@documentencoding UTF-8 -@ifinfo -@*Generated by Sphinx 5.1.1.@* -@end ifinfo -@settitle GNAT Coding Style A Guide for GNAT Developers -@defindex ge -@paragraphindent 0 -@exampleindent 4 -@finalout -@dircategory GNU Ada Tools -@direntry -* gnat-style: (gnat-style.info). gnat-style -@end direntry - -@c %**end of header - -@copying -@quotation -GNAT Coding Style: A Guide for GNAT Developers , Aug 25, 2022 - -AdaCore - -Copyright @copyright{} 2008-2022, Free Software Foundation -@end quotation - -@end copying - -@titlepage -@title GNAT Coding Style A Guide for GNAT Developers -@insertcopying -@end titlepage -@contents - -@c %** start of user preamble - -@c %** end of user preamble - -@ifnottex -@node Top -@top GNAT Coding Style A Guide for GNAT Developers -@insertcopying -@end ifnottex - -@c %**start of body -@anchor{gnat-style doc}@anchor{0} -@menu -* General:: -* Lexical Elements:: -* Declarations and Types:: -* Expressions and Names:: -* Statements:: -* Subprograms:: -* Packages and Visibility Rules:: -* Program Structure and Compilation Issues:: -* Index:: - -@end menu - -@node General,Lexical Elements,Top,Top -@anchor{gnat-style general}@anchor{1}@anchor{gnat-style gnat-coding-style-a-guide-for-gnat-developers}@anchor{2} -@chapter General - - -Most of GNAT is written in Ada using a consistent style to ensure -readability of the code. This document has been written to help -maintain this consistent style, while having a large group of developers -work on the compiler. - -For the coding style in the C parts of the compiler and run time, -see the GNU Coding Guidelines. - -This document is structured after the Ada Reference Manual. -Those familiar with that document should be able to quickly -lookup style rules for particular constructs. - -@node Lexical Elements,Declarations and Types,General,Top -@anchor{gnat-style lexical-elements}@anchor{3} -@chapter Lexical Elements - - -@menu -* Character Set and Separators:: -* Identifiers:: -* Numeric Literals:: -* Reserved Words:: -* Comments:: - -@end menu - -@node Character Set and Separators,Identifiers,,Lexical Elements -@anchor{gnat-style character-set-and-separators}@anchor{4} -@section Character Set and Separators - - -@geindex Character set - -@geindex ASCII - -@geindex Separators - -@geindex End-of-line - -@geindex Line length - -@geindex Indentation - - -@itemize * - -@item -The character set used should be plain 7-bit ASCII. -The only separators allowed are space and the end-of-line sequence. -No other control character or format effector (such as @code{HT}, -@code{VT}, @code{FF} ) -should be used. -The normal end-of-line sequence is used, which may be -@code{LF}, @code{CR/LF} or @code{CR}, -depending on the host system. An optional @code{SUB} -( @code{16#1A#} ) may be present as the -last character in the file on hosts using that character as file terminator. - -@item -Files that are checked in or distributed should be in host format. - -@item -A line should never be longer than 79 characters, not counting the line -separator. - -@item -Lines must not have trailing blanks. - -@item -Indentation is 3 characters per level for @code{if} statements, loops, and -@code{case} statements. -For exact information on required spacing between lexical -elements, see file style.adb. - -@geindex style.adb file -@end itemize - -@node Identifiers,Numeric Literals,Character Set and Separators,Lexical Elements -@anchor{gnat-style identifiers}@anchor{5} -@section Identifiers - - - -@itemize * - -@item -Identifiers will start with an upper case letter, and each letter following -an underscore will be upper case. - -@geindex Casing (for identifiers) - -Short acronyms may be all upper case. -All other letters are lower case. -An exception is for identifiers matching a foreign language. In particular, -we use all lower case where appropriate for C. - -@item -Use underscores to separate words in an identifier. - -@geindex Underscores - -@item -Try to limit your use of abbreviations in identifiers. -It is ok to make a few abbreviations, explain what they mean, and then -use them frequently, but don’t use lots of obscure abbreviations. An -example is the @code{ALI} word which stands for Ada Library -Information and is by convention always written in upper-case when -used in entity names. - -@example -procedure Find_ALI_Files; -@end example - -@item -Don’t use the variable name @code{I}, use @code{J} instead; @code{I} is too -easily confused with @code{1} in some fonts. Similarly don’t use the -variable @code{O}, which is too easily mistaken for the number @code{0}. -@end itemize - -@node Numeric Literals,Reserved Words,Identifiers,Lexical Elements -@anchor{gnat-style numeric-literals}@anchor{6} -@section Numeric Literals - - - -@itemize * - -@item -Numeric literals should include underscores where helpful for -readability. - -@geindex Underscores - -@example -1_000_000 -16#8000_0000# -3.14159_26535_89793_23846 -@end example -@end itemize - -@node Reserved Words,Comments,Numeric Literals,Lexical Elements -@anchor{gnat-style reserved-words}@anchor{7} -@section Reserved Words - - - -@itemize * - -@item -Reserved words use all lower case. - -@geindex Casing (for reserved words) - -@example -return else -@end example - -@item -The words @code{Access}, @code{Delta} and @code{Digits} are -capitalized when used as attribute_designator. -@end itemize - -@node Comments,,Reserved Words,Lexical Elements -@anchor{gnat-style comments}@anchor{8} -@section Comments - - - -@itemize * - -@item -A comment starts with @code{--} followed by two spaces. -The only exception to this rule (i.e. one space is tolerated) is when the -comment ends with a single space followed by @code{--}. -It is also acceptable to have only one space between @code{--} and the start -of the comment when the comment is at the end of a line, -after some Ada code. - -@item -Every sentence in a comment should start with an upper-case letter (including -the first letter of the comment). - -@geindex Casing (in comments) - -@item -When declarations are commented with ‘hanging’ comments, i.e. -comments after the declaration, there is no blank line before the -comment, and if it is absolutely necessary to have blank lines within -the comments, e.g. to make paragraph separations within a single comment, -these blank lines `do' have a @code{--} (unlike the -normal rule, which is to use entirely blank lines for separating -comment paragraphs). The comment starts at same level of indentation -as code it is commenting. - -@geindex Blank lines (in comments) - -@geindex Indentation - -@example -z : Integer; --- Integer value for storing value of z --- --- The previous line was a blank line. -@end example - -@item -Comments that are dubious or incomplete, or that comment on possibly -wrong or incomplete code, should be preceded or followed by @code{???}. - -@item -Comments in a subprogram body must generally be surrounded by blank lines. -An exception is a comment that follows a line containing a single keyword -( @code{begin}, @code{else}, @code{loop} ): - -@example -begin - -- Comment for the next statement - - A := 5; - - -- Comment for the B statement - - B := 6; -end; -@end example - -@item -In sequences of statements, comments at the end of the lines should be -aligned. - -@geindex Alignment (in comments) - -@example -My_Identifier := 5; -- First comment -Other_Id := 6; -- Second comment -@end example - -@item -Short comments that fit on a single line are `not' ended with a -period. Comments taking more than a line are punctuated in the normal -manner. - -@item -Comments should focus on `why' instead of `what'. -Descriptions of what subprograms do go with the specification. - -@item -Comments describing a subprogram spec should specifically mention the -formal argument names. General rule: write a comment that does not -depend on the names of things. The names are supplementary, not -sufficient, as comments. - -@item -`Do not' put two spaces after periods in comments. -@end itemize - -@node Declarations and Types,Expressions and Names,Lexical Elements,Top -@anchor{gnat-style declarations-and-types}@anchor{9} -@chapter Declarations and Types - - - -@itemize * - -@item -In entity declarations, colons must be surrounded by spaces. Colons -should be aligned. - -@geindex Alignment (in declarations) - -@example -Entity1 : Integer; -My_Entity : Integer; -@end example - -@item -Declarations should be grouped in a logical order. -Related groups of declarations may be preceded by a header comment. - -@item -All local subprograms in a subprogram or package body should be declared -before the first local subprogram body. - -@item -Do not declare local entities that hide global entities. - -@geindex Hiding of outer entities - -@item -Do not declare multiple variables in one declaration that spans lines. -Start a new declaration on each line, instead. - -@item -The defining_identifiers of global declarations serve as -comments of a sort. So don’t choose terse names, but look for names -that give useful information instead. - -@item -Local names can be shorter, because they are used only within -one context, where comments explain their purpose. - -@item -When starting an initialization or default expression on the line that follows -the declaration line, use 2 characters for indentation. - -@example -Entity1 : Integer := - Function_Name (Parameters, For_Call); -@end example - -@item -If an initialization or default expression needs to be continued on subsequent -lines, the continuations should be indented from the start of the expression. - -@example -Entity1 : Integer := Long_Function_Name - (parameters for call); -@end example -@end itemize - -@node Expressions and Names,Statements,Declarations and Types,Top -@anchor{gnat-style expressions-and-names}@anchor{a} -@chapter Expressions and Names - - - -@itemize * - -@item -Every operator must be surrounded by spaces. An exception is that -this rule does not apply to the exponentiation operator, for which -there are no specific layout rules. The reason for this exception -is that sometimes it makes clearer reading to leave out the spaces -around exponentiation. - -@geindex Operators - -@example -E := A * B**2 + 3 * (C - D); -@end example - -@item -Use parentheses where they clarify the intended association of operands -with operators: - -@geindex Parenthesization of expressions - -@example -(A / B) * C -@end example -@end itemize - -@node Statements,Subprograms,Expressions and Names,Top -@anchor{gnat-style statements}@anchor{b} -@chapter Statements - - -@menu -* Simple and Compound Statements:: -* If Statements:: -* Case Statements:: -* Loop Statements:: -* Block Statements:: - -@end menu - -@node Simple and Compound Statements,If Statements,,Statements -@anchor{gnat-style simple-and-compound-statements}@anchor{c} -@section Simple and Compound Statements - - - -@itemize * - -@item -Use only one statement or label per line. - -@item -A longer sequence_of_statements may be divided in logical -groups or separated from surrounding code using a blank line. -@end itemize - -@node If Statements,Case Statements,Simple and Compound Statements,Statements -@anchor{gnat-style if-statements}@anchor{d} -@section If Statements - - - -@itemize * - -@item -When the @code{if}, @code{elsif} or @code{else} keywords fit on the -same line with the condition and the @code{then} keyword, then the -statement is formatted as follows: - -@geindex Alignment (in an if statement) - -@example -if condition then - ... -elsif condition then - ... -else - ... -end if; -@end example - -When the above layout is not possible, @code{then} should be aligned -with @code{if}, and conditions should preferably be split before an -@code{and} or @code{or} keyword a follows: - -@example -if long_condition_that_has_to_be_split - and then continued_on_the_next_line -then - ... -end if; -@end example - -The @code{elsif}, @code{else} and @code{end if} always line up with -the @code{if} keyword. The preferred location for splitting the line -is before @code{and} or @code{or}. The continuation of a condition is -indented with two spaces or as many as needed to make nesting clear. -As an exception, if conditions are closely related either of the -following is allowed: - -@example -if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf - or else - x = asldkjhalkdsjfhhfd - or else - x = asdfadsfadsf -then - ... -end if; - -if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else - x = asldkjhalkdsjfhhfd or else - x = asdfadsfadsf -then - ... -end if; -@end example - -@item -Conditions should use short-circuit forms ( @code{and then}, -@code{or else} ), except when the operands are boolean variables -or boolean constants. - -@geindex Short-circuit forms - -@item -Complex conditions in @code{if} statements are indented two characters: - -@geindex Indentation (in if statements) - -@example -if this_complex_condition - and then that_other_one - and then one_last_one -then - ... -end if; -@end example - -There are some cases where complex conditionals can be laid out -in manners that do not follow these rules to preserve better -parallelism between branches, e.g. - -@example -if xyz.abc (gef) = 'c' - or else - xyz.abc (gef) = 'x' -then - ... -end if; -@end example - -@item -Every @code{if} block is preceded and followed by a blank line, except -where it begins or ends a sequence_of_statements. - -@geindex Blank lines (in an if statement) - -@example -A := 5; - -if A = 5 then - null; -end if; - -A := 6; -@end example -@end itemize - -@node Case Statements,Loop Statements,If Statements,Statements -@anchor{gnat-style case-statements}@anchor{e} -@section Case Statements - - - -@itemize * - -@item -Layout is as below. For long @code{case} statements, the extra indentation -can be saved by aligning the @code{when} clauses with the opening @code{case}. - -@example -case expression is - when condition => - ... - when condition => - ... -end case; -@end example -@end itemize - -@node Loop Statements,Block Statements,Case Statements,Statements -@anchor{gnat-style loop-statements}@anchor{f} -@section Loop Statements - - - -@itemize * - -@item -When possible, have @code{for} or @code{while} on one line with the -condition and the @code{loop} keyword. - -@example -for J in S'Range loop - ... -end loop; -@end example - -If the condition is too long, split the condition (see ‘If -statements’ above) and align @code{loop} with the @code{for} or -@code{while} keyword. - -@geindex Alignment (in a loop statement) - -@example -while long_condition_that_has_to_be_split - and then continued_on_the_next_line -loop - ... -end loop; -@end example - -If the loop_statement has an identifier, it is laid out as follows: - -@example -Outer : while not condition loop - ... -end Outer; -@end example -@end itemize - -@node Block Statements,,Loop Statements,Statements -@anchor{gnat-style block-statements}@anchor{10} -@section Block Statements - - - -@itemize * - -@item -The @code{declare} (optional), @code{begin} and @code{end} words -are aligned, except when the block_statement is named. There -is a blank line before the @code{begin} keyword: - -@geindex Alignment (in a block statement) - -@example -Some_Block : declare - ... - -begin - ... -end Some_Block; -@end example -@end itemize - -@node Subprograms,Packages and Visibility Rules,Statements,Top -@anchor{gnat-style subprograms}@anchor{11} -@chapter Subprograms - - -@menu -* Subprogram Declarations:: -* Subprogram Bodies:: - -@end menu - -@node Subprogram Declarations,Subprogram Bodies,,Subprograms -@anchor{gnat-style subprogram-declarations}@anchor{12} -@section Subprogram Declarations - - - -@itemize * - -@item -Do not write the @code{in} for parameters. - -@example -function Length (S : String) return Integer; -@end example - -@item -When the declaration line for a procedure or a function is too long to fit -the entire declaration (including the keyword procedure or function) on a -single line, then fold it, putting a single parameter on a line, aligning -the colons, as in: - -@example -procedure Set_Heading - (Source : String; - Count : Natural; - Pad : Character := Space; - Fill : Boolean := True); -@end example - -In the case of a function, if the entire spec does not fit on one line, then -the return may appear after the last parameter, as in: - -@example -function Head - (Source : String; - Count : Natural; - Pad : Character := Space) return String; -@end example - -Or it may appear on its own as a separate line. This form is preferred when -putting the return on the same line as the last parameter would result in -an overlong line. The return type may optionally be aligned with the types -of the parameters (usually we do this aligning if it results only in a small -number of extra spaces, and otherwise we don’t attempt to align). So two -alternative forms for the above spec are: - -@example -function Head - (Source : String; - Count : Natural; - Pad : Character := Space) - return String; - -function Head - (Source : String; - Count : Natural; - Pad : Character := Space) - return String; -@end example -@end itemize - -@node Subprogram Bodies,,Subprogram Declarations,Subprograms -@anchor{gnat-style subprogram-bodies}@anchor{13} -@section Subprogram Bodies - - - -@itemize * - -@item -Function and procedure bodies should usually be sorted alphabetically. Do -not attempt to sort them in some logical order by functionality. For a -sequence of subprogram specs, a general alphabetical sorting is also -usually appropriate, but occasionally it makes sense to group by major -function, with appropriate headers. - -@item -All subprograms have a header giving the function name, with the following -format: - -@example ------------------ --- My_Function -- ------------------ - -procedure My_Function is -begin - ... -end My_Function; -@end example - -Note that the name in the header is preceded by a single space, -not two spaces as for other comments. These headers are used on -nested subprograms as well as outer level subprograms. They may -also be used as headers for sections of comments, or collections -of declarations that are related. - -@item -Every subprogram body must have a preceding subprogram_declaration, -which includes proper client documentation so that you do not need to -read the subprogram body in order to understand what the subprogram does and -how to call it. All subprograms should be documented, without exceptions. - -@geindex Blank lines (in subprogram bodies) - -@item -A sequence of declarations may optionally be separated from the following -begin by a blank line. Just as we optionally allow blank lines in general -between declarations, this blank line should be present only if it improves -readability. Generally we avoid this blank line if the declarative part is -small (one or two lines) and the body has no blank lines, and we include it -if the declarative part is long or if the body has blank lines. - -@item -If the declarations in a subprogram contain at least one nested -subprogram body, then just before the @code{begin} of the enclosing -subprogram, there is a comment line and a blank line: - -@example --- Start of processing for Enclosing_Subprogram - -begin - ... -end Enclosing_Subprogram; -@end example - -@item -When nested subprograms are present, variables that are referenced by any -nested subprogram should precede the nested subprogram specs. For variables -that are not referenced by nested procedures, the declarations can either also -be before any of the nested subprogram specs (this is the old style, more -generally used). Or then can come just before the begin, with a header. The -following example shows the two possible styles: - -@example -procedure Style1 is - Var_Referenced_In_Nested : Integer; - Var_Referenced_Only_In_Style1 : Integer; - - proc Nested; - -- Comments ... - - ------------ - -- Nested -- - ------------ - - procedure Nested is - begin - ... - end Nested; - --- Start of processing for Style1 - -begin - ... -end Style1; - -procedure Style2 is - Var_Referenced_In_Nested : Integer; - - proc Nested; - -- Comments ... - - ------------ - -- Nested -- - ------------ - - procedure Nested is - begin - ... - end Nested; - - -- Local variables - - Var_Referenced_Only_In_Style2 : Integer; - --- Start of processing for Style2 - -begin - ... -end Style2; -@end example - -For new code, we generally prefer Style2, but we do not insist on -modifying all legacy occurrences of Style1, which is still much -more common in the sources. -@end itemize - -@node Packages and Visibility Rules,Program Structure and Compilation Issues,Subprograms,Top -@anchor{gnat-style packages-and-visibility-rules}@anchor{14} -@chapter Packages and Visibility Rules - - - -@itemize * - -@item -All program units and subprograms have their name at the end: - -@example -package P is - ... -end P; -@end example - -@item -We will use the style of @code{use} -ing @code{with} -ed packages, with -the context clauses looking like: - -@geindex use clauses - -@example -with A; use A; -with B; use B; -@end example - -@item -Names declared in the visible part of packages should be -unique, to prevent name clashes when the packages are @code{use} d. - -@geindex Name clash avoidance - -@example -package Entity is - type Entity_Kind is ...; - ... -end Entity; -@end example - -@item -After the file header comment, the context clause and unit specification -should be the first thing in a program_unit. - -@item -Preelaborate, Pure and Elaborate_Body pragmas should be added right after the -package name, indented an extra level and using the parameterless form: - -@example -package Preelaborate_Package is - pragma Preelaborate; - ... -end Preelaborate_Package; -@end example -@end itemize - -@node Program Structure and Compilation Issues,Index,Packages and Visibility Rules,Top -@anchor{gnat-style program-structure-and-compilation-issues}@anchor{15} -@chapter Program Structure and Compilation Issues - - - -@itemize * - -@item -Every GNAT source file must be compiled with the @code{-gnatg} -switch to check the coding style. -(Note that you should look at -style.adb to see the lexical rules enforced by @code{-gnatg} ). - -@geindex -gnatg option (to gcc) - -@geindex style.adb file - -@item -Each source file should contain only one compilation unit. - -@item -Filenames should be 8 or fewer characters, followed by the @code{.adb} -extension for a body or @code{.ads} for a spec. - -@geindex File name length - -@item -Unit names should be distinct when ‘krunch’ed to 8 characters -(see krunch.ads) and the filenames should match the unit name, -except that they are all lower case. - -@geindex krunch.ads file -@end itemize - -@menu -* GNU Free Documentation License:: - -@end menu - -@node GNU Free Documentation License,,,Program Structure and Compilation Issues -@anchor{share/gnu_free_documentation_license doc}@anchor{16}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{17}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{18} -@section GNU Free Documentation License - - -Version 1.3, 3 November 2008 - -Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc -@indicateurl{https://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -`Preamble' - -The purpose of this License is to make a manual, textbook, or other -functional and useful document “free” in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of “copyleft”, which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -`1. APPLICABILITY AND DEFINITIONS' - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The `Document', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as “`you'”. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A “`Modified Version'” of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A “`Secondary Section'” is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document’s overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The “`Invariant Sections'” are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The “`Cover Texts'” are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A “`Transparent'” copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not “Transparent” is called `Opaque'. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The “`Title Page'” means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, “Title Page” means -the text near the most prominent appearance of the work’s title, -preceding the beginning of the body of the text. - -The “`publisher'” means any person or entity that distributes -copies of the Document to the public. - -A section “`Entitled XYZ'” means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as “`Acknowledgements'”, -“`Dedications'”, “`Endorsements'”, or “`History'”.) -To “`Preserve the Title'” -of such a section when you modify the Document means that it remains a -section “Entitled XYZ” according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -`2. VERBATIM COPYING' - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -`3. COPYING IN QUANTITY' - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document’s license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -`4. MODIFICATIONS' - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - - -@enumerate A - -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document’s license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled “History”, Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled “History” in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the “History” section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled “Acknowledgements” or “Dedications”, -Preserve the Title of the section, and preserve in the section all -the substance and tone of each of the contributor acknowledgements -and/or dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled “Endorsements”. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled “Endorsements” -or to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version’s license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled “Endorsements”, provided it contains -nothing but endorsements of your Modified Version by various -parties—for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -`5. COMBINING DOCUMENTS' - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled “History” -in the various original documents, forming one section Entitled -“History”; likewise combine any sections Entitled “Acknowledgements”, -and any sections Entitled “Dedications”. You must delete all sections -Entitled “Endorsements”. - -`6. COLLECTIONS OF DOCUMENTS' - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -`7. AGGREGATION WITH INDEPENDENT WORKS' - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an “aggregate” if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation’s users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document’s Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -`8. TRANSLATION' - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled “Acknowledgements”, -“Dedications”, or “History”, the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -`9. TERMINATION' - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -`10. FUTURE REVISIONS OF THIS LICENSE' - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@indicateurl{https://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License “or any later version” applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy’s public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -`11. RELICENSING' - -“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -“Massive Multiauthor Collaboration” (or “MMC”) contained in the -site means any set of copyrightable works thus published on the MMC -site. - -“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -“Incorporate” means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is “eligible for relicensing” if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -`ADDENDUM: How to use this License for your documents' - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@quotation - -Copyright © YEAR YOUR NAME. -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 -or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled “GNU -Free Documentation License”. -@end quotation - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the “with … Texts.” line with this: - -@quotation - -with the Invariant Sections being LIST THEIR TITLES, with the -Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. -@end quotation - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@node Index,,Program Structure and Compilation Issues,Top -@unnumbered Index - - -@printindex ge - - -@c %**end of body -@bye diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi deleted file mode 100644 index fbd8bb8d6b2..00000000000 --- a/gcc/ada/gnat_rm.texi +++ /dev/null @@ -1,30385 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename gnat_rm.info -@documentencoding UTF-8 -@ifinfo -@*Generated by Sphinx 5.2.3.@* -@end ifinfo -@settitle GNAT Reference Manual -@defindex ge -@paragraphindent 0 -@exampleindent 4 -@finalout -@dircategory GNU Ada Tools -@direntry -* gnat_rm: (gnat_rm.info). gnat_rm -@end direntry - -@c %**end of header - -@copying -@quotation -GNAT Reference Manual , Oct 27, 2022 - -AdaCore - -Copyright @copyright{} 2008-2022, Free Software Foundation -@end quotation - -@end copying - -@titlepage -@title GNAT Reference Manual -@insertcopying -@end titlepage -@contents - -@c %** start of user preamble - -@c %** end of user preamble - -@ifnottex -@node Top -@top GNAT Reference Manual -@insertcopying -@end ifnottex - -@c %**start of body -@anchor{gnat_rm doc}@anchor{0} -`GNAT, The GNU Ada Development Environment' - - -@include gcc-common.texi -GCC version @value{version-GCC}@* -AdaCore - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being “GNAT Reference -Manual”, and with no Back-Cover Texts. A copy of the license is -included in the section entitled @ref{1,,GNU Free Documentation License}. - -@menu -* About This Guide:: -* Implementation Defined Pragmas:: -* Implementation Defined Aspects:: -* Implementation Defined Attributes:: -* Standard and Implementation Defined Restrictions:: -* Implementation Advice:: -* Implementation Defined Characteristics:: -* Intrinsic Subprograms:: -* Representation Clauses and Pragmas:: -* Standard Library Routines:: -* The Implementation of Standard I/O:: -* The GNAT Library:: -* Interfacing to Other Languages:: -* Specialized Needs Annexes:: -* Implementation of Specific Ada Features:: -* Implementation of Ada 2012 Features:: -* Security Hardening Features:: -* Obsolescent Features:: -* Compatibility and Porting Guide:: -* GNU Free Documentation License:: -* Index:: - -@detailmenu - --- The Detailed Node Listing --- - -About This Guide - -* What This Reference Manual Contains:: -* Conventions:: -* Related Information:: - -Implementation Defined Pragmas - -* Pragma Abort_Defer:: -* Pragma Abstract_State:: -* Pragma Ada_83:: -* Pragma Ada_95:: -* Pragma Ada_05:: -* Pragma Ada_2005:: -* Pragma Ada_12:: -* Pragma Ada_2012:: -* Pragma Ada_2022:: -* Pragma Aggregate_Individually_Assign:: -* Pragma Allow_Integer_Address:: -* Pragma Annotate:: -* Pragma Assert:: -* Pragma Assert_And_Cut:: -* Pragma Assertion_Policy:: -* Pragma Assume:: -* Pragma Assume_No_Invalid_Values:: -* Pragma Async_Readers:: -* Pragma Async_Writers:: -* Pragma Attribute_Definition:: -* Pragma C_Pass_By_Copy:: -* Pragma Check:: -* Pragma Check_Float_Overflow:: -* Pragma Check_Name:: -* Pragma Check_Policy:: -* Pragma Comment:: -* Pragma Common_Object:: -* Pragma Compile_Time_Error:: -* Pragma Compile_Time_Warning:: -* Pragma Complete_Representation:: -* Pragma Complex_Representation:: -* Pragma Component_Alignment:: -* Pragma Constant_After_Elaboration:: -* Pragma Contract_Cases:: -* Pragma Convention_Identifier:: -* Pragma CPP_Class:: -* Pragma CPP_Constructor:: -* Pragma CPP_Virtual:: -* Pragma CPP_Vtable:: -* Pragma CPU:: -* Pragma Deadline_Floor:: -* Pragma Default_Initial_Condition:: -* Pragma Debug:: -* Pragma Debug_Policy:: -* Pragma Default_Scalar_Storage_Order:: -* Pragma Default_Storage_Pool:: -* Pragma Depends:: -* Pragma Detect_Blocking:: -* Pragma Disable_Atomic_Synchronization:: -* Pragma Dispatching_Domain:: -* Pragma Effective_Reads:: -* Pragma Effective_Writes:: -* Pragma Elaboration_Checks:: -* Pragma Eliminate:: -* Pragma Enable_Atomic_Synchronization:: -* Pragma Export_Function:: -* Pragma Export_Object:: -* Pragma Export_Procedure:: -* Pragma Export_Valued_Procedure:: -* Pragma Extend_System:: -* Pragma Extensions_Allowed:: -* Pragma Extensions_Visible:: -* Pragma External:: -* Pragma External_Name_Casing:: -* Pragma Fast_Math:: -* Pragma Favor_Top_Level:: -* Pragma Finalize_Storage_Only:: -* Pragma Float_Representation:: -* Pragma Ghost:: -* Pragma Global:: -* Pragma Ident:: -* Pragma Ignore_Pragma:: -* Pragma Implementation_Defined:: -* Pragma Implemented:: -* Pragma Implicit_Packing:: -* Pragma Import_Function:: -* Pragma Import_Object:: -* Pragma Import_Procedure:: -* Pragma Import_Valued_Procedure:: -* Pragma Independent:: -* Pragma Independent_Components:: -* Pragma Initial_Condition:: -* Pragma Initialize_Scalars:: -* Pragma Initializes:: -* Pragma Inline_Always:: -* Pragma Inline_Generic:: -* Pragma Interface:: -* Pragma Interface_Name:: -* Pragma Interrupt_Handler:: -* Pragma Interrupt_State:: -* Pragma Invariant:: -* Pragma Keep_Names:: -* Pragma License:: -* Pragma Link_With:: -* Pragma Linker_Alias:: -* Pragma Linker_Constructor:: -* Pragma Linker_Destructor:: -* Pragma Linker_Section:: -* Pragma Lock_Free:: -* Pragma Loop_Invariant:: -* Pragma Loop_Optimize:: -* Pragma Loop_Variant:: -* Pragma Machine_Attribute:: -* Pragma Main:: -* Pragma Main_Storage:: -* Pragma Max_Queue_Length:: -* Pragma No_Body:: -* Pragma No_Caching:: -* Pragma No_Component_Reordering:: -* Pragma No_Elaboration_Code_All:: -* Pragma No_Heap_Finalization:: -* Pragma No_Inline:: -* Pragma No_Return:: -* Pragma No_Strict_Aliasing:: -* Pragma No_Tagged_Streams:: -* Pragma Normalize_Scalars:: -* Pragma Obsolescent:: -* Pragma Optimize_Alignment:: -* Pragma Ordered:: -* Pragma Overflow_Mode:: -* Pragma Overriding_Renamings:: -* Pragma Partition_Elaboration_Policy:: -* Pragma Part_Of:: -* Pragma Passive:: -* Pragma Persistent_BSS:: -* Pragma Post:: -* Pragma Postcondition:: -* Pragma Post_Class:: -* Pragma Pre:: -* Pragma Precondition:: -* Pragma Predicate:: -* Pragma Predicate_Failure:: -* Pragma Preelaborable_Initialization:: -* Pragma Prefix_Exception_Messages:: -* Pragma Pre_Class:: -* Pragma Priority_Specific_Dispatching:: -* Pragma Profile:: -* Pragma Profile_Warnings:: -* Pragma Propagate_Exceptions:: -* Pragma Provide_Shift_Operators:: -* Pragma Psect_Object:: -* Pragma Pure_Function:: -* Pragma Rational:: -* Pragma Ravenscar:: -* Pragma Refined_Depends:: -* Pragma Refined_Global:: -* Pragma Refined_Post:: -* Pragma Refined_State:: -* Pragma Relative_Deadline:: -* Pragma Remote_Access_Type:: -* Pragma Rename_Pragma:: -* Pragma Restricted_Run_Time:: -* Pragma Restriction_Warnings:: -* Pragma Reviewable:: -* Pragma Secondary_Stack_Size:: -* Pragma Share_Generic:: -* Pragma Shared:: -* Pragma Short_Circuit_And_Or:: -* Pragma Short_Descriptors:: -* Pragma Simple_Storage_Pool_Type:: -* Pragma Source_File_Name:: -* Pragma Source_File_Name_Project:: -* Pragma Source_Reference:: -* Pragma SPARK_Mode:: -* Pragma Static_Elaboration_Desired:: -* Pragma Stream_Convert:: -* Pragma Style_Checks:: -* Pragma Subtitle:: -* Pragma Suppress:: -* Pragma Suppress_All:: -* Pragma Suppress_Debug_Info:: -* Pragma Suppress_Exception_Locations:: -* Pragma Suppress_Initialization:: -* Pragma Task_Name:: -* Pragma Task_Storage:: -* Pragma Test_Case:: -* Pragma Thread_Local_Storage:: -* Pragma Time_Slice:: -* Pragma Title:: -* Pragma Type_Invariant:: -* Pragma Type_Invariant_Class:: -* Pragma Unchecked_Union:: -* Pragma Unevaluated_Use_Of_Old:: -* Pragma Unimplemented_Unit:: -* Pragma Universal_Aliasing:: -* Pragma Unmodified:: -* Pragma Unreferenced:: -* Pragma Unreferenced_Objects:: -* Pragma Unreserve_All_Interrupts:: -* Pragma Unsuppress:: -* Pragma Use_VADS_Size:: -* Pragma Unused:: -* Pragma Validity_Checks:: -* Pragma Volatile:: -* Pragma Volatile_Full_Access:: -* Pragma Volatile_Function:: -* Pragma Warning_As_Error:: -* Pragma Warnings:: -* Pragma Weak_External:: -* Pragma Wide_Character_Encoding:: - -Implementation Defined Aspects - -* Aspect Abstract_State:: -* Aspect Annotate:: -* Aspect Async_Readers:: -* Aspect Async_Writers:: -* Aspect Constant_After_Elaboration:: -* Aspect Contract_Cases:: -* Aspect Depends:: -* Aspect Default_Initial_Condition:: -* Aspect Dimension:: -* Aspect Dimension_System:: -* Aspect Disable_Controlled:: -* Aspect Effective_Reads:: -* Aspect Effective_Writes:: -* Aspect Extensions_Visible:: -* Aspect Favor_Top_Level:: -* Aspect Ghost:: -* Aspect Global:: -* Aspect Initial_Condition:: -* Aspect Initializes:: -* Aspect Inline_Always:: -* Aspect Invariant:: -* Aspect Invariant’Class:: -* Aspect Iterable:: -* Aspect Linker_Section:: -* Aspect Lock_Free:: -* Aspect Max_Queue_Length:: -* Aspect No_Caching:: -* Aspect No_Elaboration_Code_All:: -* Aspect No_Inline:: -* Aspect No_Tagged_Streams:: -* Aspect No_Task_Parts:: -* Aspect Object_Size:: -* Aspect Obsolescent:: -* Aspect Part_Of:: -* Aspect Persistent_BSS:: -* Aspect Predicate:: -* Aspect Pure_Function:: -* Aspect Refined_Depends:: -* Aspect Refined_Global:: -* Aspect Refined_Post:: -* Aspect Refined_State:: -* Aspect Relaxed_Initialization:: -* Aspect Remote_Access_Type:: -* Aspect Secondary_Stack_Size:: -* Aspect Scalar_Storage_Order:: -* Aspect Shared:: -* Aspect Simple_Storage_Pool:: -* Aspect Simple_Storage_Pool_Type:: -* Aspect SPARK_Mode:: -* Aspect Suppress_Debug_Info:: -* Aspect Suppress_Initialization:: -* Aspect Test_Case:: -* Aspect Thread_Local_Storage:: -* Aspect Universal_Aliasing:: -* Aspect Unmodified:: -* Aspect Unreferenced:: -* Aspect Unreferenced_Objects:: -* Aspect Value_Size:: -* Aspect Volatile_Full_Access:: -* Aspect Volatile_Function:: -* Aspect Warnings:: - -Implementation Defined Attributes - -* Attribute Abort_Signal:: -* Attribute Address_Size:: -* Attribute Asm_Input:: -* Attribute Asm_Output:: -* Attribute Atomic_Always_Lock_Free:: -* Attribute Bit:: -* Attribute Bit_Position:: -* Attribute Code_Address:: -* Attribute Compiler_Version:: -* Attribute Constrained:: -* Attribute Default_Bit_Order:: -* Attribute Default_Scalar_Storage_Order:: -* Attribute Deref:: -* Attribute Descriptor_Size:: -* Attribute Elaborated:: -* Attribute Elab_Body:: -* Attribute Elab_Spec:: -* Attribute Elab_Subp_Body:: -* Attribute Emax:: -* Attribute Enabled:: -* Attribute Enum_Rep:: -* Attribute Enum_Val:: -* Attribute Epsilon:: -* Attribute Fast_Math:: -* Attribute Finalization_Size:: -* Attribute Fixed_Value:: -* Attribute From_Any:: -* Attribute Has_Access_Values:: -* Attribute Has_Discriminants:: -* Attribute Has_Tagged_Values:: -* Attribute Img:: -* Attribute Initialized:: -* Attribute Integer_Value:: -* Attribute Invalid_Value:: -* Attribute Iterable:: -* Attribute Large:: -* Attribute Library_Level:: -* Attribute Loop_Entry:: -* Attribute Machine_Size:: -* Attribute Mantissa:: -* Attribute Maximum_Alignment:: -* Attribute Max_Integer_Size:: -* Attribute Mechanism_Code:: -* Attribute Null_Parameter:: -* Attribute Object_Size:: -* Attribute Old:: -* Attribute Passed_By_Reference:: -* Attribute Pool_Address:: -* Attribute Range_Length:: -* Attribute Restriction_Set:: -* Attribute Result:: -* Attribute Safe_Emax:: -* Attribute Safe_Large:: -* Attribute Safe_Small:: -* Attribute Scalar_Storage_Order:: -* Attribute Simple_Storage_Pool:: -* Attribute Small:: -* Attribute Small_Denominator:: -* Attribute Small_Numerator:: -* Attribute Storage_Unit:: -* Attribute Stub_Type:: -* Attribute System_Allocator_Alignment:: -* Attribute Target_Name:: -* Attribute To_Address:: -* Attribute To_Any:: -* Attribute Type_Class:: -* Attribute Type_Key:: -* Attribute TypeCode:: -* Attribute Unconstrained_Array:: -* Attribute Universal_Literal_String:: -* Attribute Unrestricted_Access:: -* Attribute Update:: -* Attribute Valid_Value:: -* Attribute Valid_Scalars:: -* Attribute VADS_Size:: -* Attribute Value_Size:: -* Attribute Wchar_T_Size:: -* Attribute Word_Size:: - -Standard and Implementation Defined Restrictions - -* Partition-Wide Restrictions:: -* Program Unit Level Restrictions:: - -Partition-Wide Restrictions - -* Immediate_Reclamation:: -* Max_Asynchronous_Select_Nesting:: -* Max_Entry_Queue_Length:: -* Max_Protected_Entries:: -* Max_Select_Alternatives:: -* Max_Storage_At_Blocking:: -* Max_Task_Entries:: -* Max_Tasks:: -* No_Abort_Statements:: -* No_Access_Parameter_Allocators:: -* No_Access_Subprograms:: -* No_Allocators:: -* No_Anonymous_Allocators:: -* No_Asynchronous_Control:: -* No_Calendar:: -* No_Coextensions:: -* No_Default_Initialization:: -* No_Delay:: -* No_Dependence:: -* No_Direct_Boolean_Operators:: -* No_Dispatch:: -* No_Dispatching_Calls:: -* No_Dynamic_Attachment:: -* No_Dynamic_Priorities:: -* No_Entry_Calls_In_Elaboration_Code:: -* No_Enumeration_Maps:: -* No_Exception_Handlers:: -* No_Exception_Propagation:: -* No_Exception_Registration:: -* No_Exceptions:: -* No_Finalization:: -* No_Fixed_Point:: -* No_Floating_Point:: -* No_Implicit_Conditionals:: -* No_Implicit_Dynamic_Code:: -* No_Implicit_Heap_Allocations:: -* No_Implicit_Protected_Object_Allocations:: -* No_Implicit_Task_Allocations:: -* No_Initialize_Scalars:: -* No_IO:: -* No_Local_Allocators:: -* No_Local_Protected_Objects:: -* No_Local_Tagged_Types:: -* No_Local_Timing_Events:: -* No_Long_Long_Integers:: -* No_Multiple_Elaboration:: -* No_Nested_Finalization:: -* No_Protected_Type_Allocators:: -* No_Protected_Types:: -* No_Recursion:: -* No_Reentrancy:: -* No_Relative_Delay:: -* No_Requeue_Statements:: -* No_Secondary_Stack:: -* No_Select_Statements:: -* No_Specific_Termination_Handlers:: -* No_Specification_of_Aspect:: -* No_Standard_Allocators_After_Elaboration:: -* No_Standard_Storage_Pools:: -* No_Stream_Optimizations:: -* No_Streams:: -* No_Tagged_Type_Registration:: -* No_Task_Allocators:: -* No_Task_At_Interrupt_Priority:: -* No_Task_Attributes_Package:: -* No_Task_Hierarchy:: -* No_Task_Termination:: -* No_Tasking:: -* No_Terminate_Alternatives:: -* No_Unchecked_Access:: -* No_Unchecked_Conversion:: -* No_Unchecked_Deallocation:: -* No_Use_Of_Entity:: -* Pure_Barriers:: -* Simple_Barriers:: -* Static_Priorities:: -* Static_Storage_Size:: - -Program Unit Level Restrictions - -* No_Elaboration_Code:: -* No_Dynamic_Accessibility_Checks:: -* No_Dynamic_Sized_Objects:: -* No_Entry_Queue:: -* No_Implementation_Aspect_Specifications:: -* No_Implementation_Attributes:: -* No_Implementation_Identifiers:: -* No_Implementation_Pragmas:: -* No_Implementation_Restrictions:: -* No_Implementation_Units:: -* No_Implicit_Aliasing:: -* No_Implicit_Loops:: -* No_Obsolescent_Features:: -* No_Wide_Characters:: -* Static_Dispatch_Tables:: -* SPARK_05:: - -Implementation Advice - -* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. -* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. -* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. -* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. -* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. -* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. -* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. -* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. -* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. -* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. -* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. -* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. -* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. -* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. -* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. -* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. -* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. -* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. -* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. -* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. -* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. -* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. -* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. -* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. -* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. -* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. -* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. -* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. -* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. -* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. -* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. -* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. -* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. -* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. -* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. -* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. -* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. -* RM A.18; Containers: RM A 18 Containers. -* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. -* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. -* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. -* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. -* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. -* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. -* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. -* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. -* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. -* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. -* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. -* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. -* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. -* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. -* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. -* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. -* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. -* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. -* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. -* RM F(7); COBOL Support: RM F 7 COBOL Support. -* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. -* RM G; Numerics: RM G Numerics. -* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. -* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. -* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. -* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. -* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. - -Intrinsic Subprograms - -* Intrinsic Operators:: -* Compilation_ISO_Date:: -* Compilation_Date:: -* Compilation_Time:: -* Enclosing_Entity:: -* Exception_Information:: -* Exception_Message:: -* Exception_Name:: -* File:: -* Line:: -* Shifts and Rotates:: -* Source_Location:: - -Representation Clauses and Pragmas - -* Alignment Clauses:: -* Size Clauses:: -* Storage_Size Clauses:: -* Size of Variant Record Objects:: -* Biased Representation:: -* Value_Size and Object_Size Clauses:: -* Component_Size Clauses:: -* Bit_Order Clauses:: -* Effect of Bit_Order on Byte Ordering:: -* Pragma Pack for Arrays:: -* Pragma Pack for Records:: -* Record Representation Clauses:: -* Handling of Records with Holes:: -* Enumeration Clauses:: -* Address Clauses:: -* Use of Address Clauses for Memory-Mapped I/O:: -* Effect of Convention on Representation:: -* Conventions and Anonymous Access Types:: -* Determining the Representations chosen by GNAT:: - -The Implementation of Standard I/O - -* Standard I/O Packages:: -* FORM Strings:: -* Direct_IO:: -* Sequential_IO:: -* Text_IO:: -* Wide_Text_IO:: -* Wide_Wide_Text_IO:: -* Stream_IO:: -* Text Translation:: -* Shared Files:: -* Filenames encoding:: -* File content encoding:: -* Open Modes:: -* Operations on C Streams:: -* Interfacing to C Streams:: - -Text_IO - -* Stream Pointer Positioning:: -* Reading and Writing Non-Regular Files:: -* Get_Immediate:: -* Treating Text_IO Files as Streams:: -* Text_IO Extensions:: -* Text_IO Facilities for Unbounded Strings:: - -Wide_Text_IO - -* Stream Pointer Positioning: Stream Pointer Positioning<2>. -* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. - -Wide_Wide_Text_IO - -* Stream Pointer Positioning: Stream Pointer Positioning<3>. -* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. - -The GNAT Library - -* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. -* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. -* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. -* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. -* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. -* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. -* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. -* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. -* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. -* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. -* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. -* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. -* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. -* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. -* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. -* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. -* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. -* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. -* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. -* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. -* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. -* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. -* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. -* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. -* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. -* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. -* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. -* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. -* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. -* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. -* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. -* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. -* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. -* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. -* GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. -* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. -* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. -* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. -* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. -* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. -* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. -* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. -* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. -* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. -* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. -* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. -* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. -* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. -* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. -* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. -* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. -* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. -* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. -* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. -* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. -* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. -* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. -* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. -* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. -* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. -* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. -* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. -* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. -* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. -* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. -* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. -* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. -* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. -* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. -* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. -* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. -* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. -* GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. -* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. -* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. -* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. -* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. -* GNAT.IO (g-io.ads): GNAT IO g-io ads. -* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. -* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. -* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. -* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. -* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. -* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. -* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. -* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. -* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. -* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. -* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. -* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. -* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. -* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. -* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. -* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. -* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. -* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. -* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. -* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. -* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. -* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. -* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. -* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. -* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. -* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. -* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. -* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. -* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. -* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. -* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. -* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. -* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. -* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. -* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. -* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. -* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. -* GNAT.Table (g-table.ads): GNAT Table g-table ads. -* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. -* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. -* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. -* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. -* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. -* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. -* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. -* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. -* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. -* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. -* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. -* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. -* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. -* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. -* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. -* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. -* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. -* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. -* System.Assertions (s-assert.ads): System Assertions s-assert ads. -* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. -* System.Memory (s-memory.ads): System Memory s-memory ads. -* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. -* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. -* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. -* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. -* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. -* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. -* System.Rident (s-rident.ads): System Rident s-rident ads. -* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. -* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. -* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. -* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. - -Interfacing to Other Languages - -* Interfacing to C:: -* Interfacing to C++:: -* Interfacing to COBOL:: -* Interfacing to Fortran:: -* Interfacing to non-GNAT Ada code:: - -Implementation of Specific Ada Features - -* Machine Code Insertions:: -* GNAT Implementation of Tasking:: -* GNAT Implementation of Shared Passive Packages:: -* Code Generation for Array Aggregates:: -* The Size of Discriminated Records with Default Discriminants:: -* Image Values For Nonscalar Types:: -* Strict Conformance to the Ada Reference Manual:: - -GNAT Implementation of Tasking - -* Mapping Ada Tasks onto the Underlying Kernel Threads:: -* Ensuring Compliance with the Real-Time Annex:: -* Support for Locking Policies:: - -Code Generation for Array Aggregates - -* Static constant aggregates with static bounds:: -* Constant aggregates with unconstrained nominal types:: -* Aggregates with static bounds:: -* Aggregates with nonstatic bounds:: -* Aggregates in assignment statements:: - -Security Hardening Features - -* Register Scrubbing:: -* Stack Scrubbing:: -* Hardened Conditionals:: -* Hardened Booleans:: -* Control Flow Redundancy:: - -Obsolescent Features - -* pragma No_Run_Time:: -* pragma Ravenscar:: -* pragma Restricted_Run_Time:: -* pragma Task_Info:: -* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. - -Compatibility and Porting Guide - -* Writing Portable Fixed-Point Declarations:: -* Compatibility with Ada 83:: -* Compatibility between Ada 95 and Ada 2005:: -* Implementation-dependent characteristics:: -* Compatibility with Other Ada Systems:: -* Representation Clauses:: -* Compatibility with HP Ada 83:: - -Compatibility with Ada 83 - -* Legal Ada 83 programs that are illegal in Ada 95:: -* More deterministic semantics:: -* Changed semantics:: -* Other language compatibility issues:: - -Implementation-dependent characteristics - -* Implementation-defined pragmas:: -* Implementation-defined attributes:: -* Libraries:: -* Elaboration order:: -* Target-specific aspects:: - -@end detailmenu -@end menu - -@node About This Guide,Implementation Defined Pragmas,Top,Top -@anchor{gnat_rm/about_this_guide doc}@anchor{2}@anchor{gnat_rm/about_this_guide about-this-guide}@anchor{3}@anchor{gnat_rm/about_this_guide gnat-reference-manual}@anchor{4}@anchor{gnat_rm/about_this_guide id1}@anchor{5} -@chapter About This Guide - - - -This manual contains useful information in writing programs using the -GNAT compiler. It includes information on implementation dependent -characteristics of GNAT, including all the information required by -Annex M of the Ada language standard. - -GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be -invoked in Ada 83 compatibility mode. -By default, GNAT assumes Ada 2012, -but you can override with a compiler switch -to explicitly specify the language version. -(Please refer to the `GNAT User’s Guide' for details on these switches.) -Throughout this manual, references to ‘Ada’ without a year suffix -apply to all the Ada versions of the language. - -Ada is designed to be highly portable. -In general, a program will have the same effect even when compiled by -different compilers on different platforms. -However, since Ada is designed to be used in a -wide variety of applications, it also contains a number of system -dependent features to be used in interfacing to the external world. - -@geindex Implementation-dependent features - -@geindex Portability - -Note: Any program that makes use of implementation-dependent features -may be non-portable. You should follow good programming practice and -isolate and clearly document any sections of your program that make use -of these features in a non-portable manner. - -@menu -* What This Reference Manual Contains:: -* Conventions:: -* Related Information:: - -@end menu - -@node What This Reference Manual Contains,Conventions,,About This Guide -@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} -@section What This Reference Manual Contains - - -This reference manual contains the following chapters: - - -@itemize * - -@item -@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent -pragmas, which can be used to extend and enhance the functionality of the -compiler. - -@item -@ref{8,,Implementation Defined Attributes}, lists GNAT -implementation-dependent attributes, which can be used to extend and -enhance the functionality of the compiler. - -@item -@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT -implementation-dependent restrictions, which can be used to extend and -enhance the functionality of the compiler. - -@item -@ref{a,,Implementation Advice}, provides information on generally -desirable behavior which are not requirements that all compilers must -follow since it cannot be provided on all systems, or which may be -undesirable on some systems. - -@item -@ref{b,,Implementation Defined Characteristics}, provides a guide to -minimizing implementation dependent features. - -@item -@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms -implemented by GNAT, and how they can be imported into user -application programs. - -@item -@ref{d,,Representation Clauses and Pragmas}, describes in detail the -way that GNAT represents data, and in particular the exact set -of representation clauses and pragmas that is accepted. - -@item -@ref{e,,Standard Library Routines}, provides a listing of packages and a -brief description of the functionality that is provided by Ada’s -extensive set of standard library routines as implemented by GNAT. - -@item -@ref{f,,The Implementation of Standard I/O}, details how the GNAT -implementation of the input-output facilities. - -@item -@ref{10,,The GNAT Library}, is a catalog of packages that complement -the Ada predefined library. - -@item -@ref{11,,Interfacing to Other Languages}, describes how programs -written in Ada using GNAT can be interfaced to other programming -languages. - -@item -@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all -of the specialized needs annexes. - -@item -@ref{13,,Implementation of Specific Ada Features}, discusses issues related -to GNAT’s implementation of machine code insertions, tasking, and several -other features. - -@item -@ref{14,,Implementation of Ada 2012 Features}, describes the status of the -GNAT implementation of the Ada 2012 language standard. - -@item -@ref{15,,Security Hardening Features} documents GNAT extensions aimed -at security hardening. - -@item -@ref{16,,Obsolescent Features} documents implementation dependent features, -including pragmas and attributes, which are considered obsolescent, since -there are other preferred ways of achieving the same results. These -obsolescent forms are retained for backwards compatibility. - -@item -@ref{17,,Compatibility and Porting Guide} presents some guidelines for -developing portable Ada code, describes the compatibility issues that -may arise between GNAT and other Ada compilation systems (including those -for Ada 83), and shows how GNAT can expedite porting applications -developed in other Ada environments. - -@item -@ref{1,,GNU Free Documentation License} contains the license for this document. -@end itemize - -@geindex Ada 95 Language Reference Manual - -@geindex Ada 2005 Language Reference Manual - -This reference manual assumes a basic familiarity with the Ada 95 language, as -described in the -@cite{International Standard ANSI/ISO/IEC-8652:1995}. -It does not require knowledge of the new features introduced by Ada 2005 or -Ada 2012. -All three reference manuals are included in the GNAT documentation -package. - -@node Conventions,Related Information,What This Reference Manual Contains,About This Guide -@anchor{gnat_rm/about_this_guide conventions}@anchor{18} -@section Conventions - - -@geindex Conventions -@geindex typographical - -@geindex Typographical conventions - -Following are examples of the typographical and graphic conventions used -in this guide: - - -@itemize * - -@item -@code{Functions}, @code{utility program names}, @code{standard names}, -and @code{classes}. - -@item -@code{Option flags} - -@item -@code{File names} - -@item -@code{Variables} - -@item -`Emphasis' - -@item -[optional information or parameters] - -@item -Examples are described by text - -@example -and then shown this way. -@end example - -@item -Commands that are entered by the user are shown as preceded by a prompt string -comprising the @code{$} character followed by a space. -@end itemize - -@node Related Information,,Conventions,About This Guide -@anchor{gnat_rm/about_this_guide related-information}@anchor{19} -@section Related Information - - -See the following documents for further information on GNAT: - - -@itemize * - -@item -@cite{GNAT User’s Guide for Native Platforms}, -which provides information on how to use the -GNAT development environment. - -@item -@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. - -@item -@cite{Ada 95 Annotated Reference Manual}, which is an annotated version -of the Ada 95 standard. The annotations describe -detailed aspects of the design decision, and in particular contain useful -sections on Ada 83 compatibility. - -@item -@cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. - -@item -@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version -of the Ada 2005 standard. The annotations describe -detailed aspects of the design decision. - -@item -@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. - -@item -@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, -which contains specific information on compatibility between GNAT and -DEC Ada 83 systems. - -@item -@cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which -describes in detail the pragmas and attributes provided by the DEC Ada 83 -compiler system. -@end itemize - -@node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top -@anchor{gnat_rm/implementation_defined_pragmas doc}@anchor{1a}@anchor{gnat_rm/implementation_defined_pragmas id1}@anchor{1b}@anchor{gnat_rm/implementation_defined_pragmas implementation-defined-pragmas}@anchor{7} -@chapter Implementation Defined Pragmas - - -Ada defines a set of pragmas that can be used to supply additional -information to the compiler. These language defined pragmas are -implemented in GNAT and work as described in the Ada Reference Manual. - -In addition, Ada allows implementations to define additional pragmas -whose meaning is defined by the implementation. GNAT provides a number -of these implementation-defined pragmas, which can be used to extend -and enhance the functionality of the compiler. This section of the GNAT -Reference Manual describes these additional pragmas. - -Note that any program using these pragmas might not be portable to other -compilers (although GNAT implements this set of pragmas on all -platforms). Therefore if portability to other compilers is an important -consideration, the use of these pragmas should be minimized. - -@menu -* Pragma Abort_Defer:: -* Pragma Abstract_State:: -* Pragma Ada_83:: -* Pragma Ada_95:: -* Pragma Ada_05:: -* Pragma Ada_2005:: -* Pragma Ada_12:: -* Pragma Ada_2012:: -* Pragma Ada_2022:: -* Pragma Aggregate_Individually_Assign:: -* Pragma Allow_Integer_Address:: -* Pragma Annotate:: -* Pragma Assert:: -* Pragma Assert_And_Cut:: -* Pragma Assertion_Policy:: -* Pragma Assume:: -* Pragma Assume_No_Invalid_Values:: -* Pragma Async_Readers:: -* Pragma Async_Writers:: -* Pragma Attribute_Definition:: -* Pragma C_Pass_By_Copy:: -* Pragma Check:: -* Pragma Check_Float_Overflow:: -* Pragma Check_Name:: -* Pragma Check_Policy:: -* Pragma Comment:: -* Pragma Common_Object:: -* Pragma Compile_Time_Error:: -* Pragma Compile_Time_Warning:: -* Pragma Complete_Representation:: -* Pragma Complex_Representation:: -* Pragma Component_Alignment:: -* Pragma Constant_After_Elaboration:: -* Pragma Contract_Cases:: -* Pragma Convention_Identifier:: -* Pragma CPP_Class:: -* Pragma CPP_Constructor:: -* Pragma CPP_Virtual:: -* Pragma CPP_Vtable:: -* Pragma CPU:: -* Pragma Deadline_Floor:: -* Pragma Default_Initial_Condition:: -* Pragma Debug:: -* Pragma Debug_Policy:: -* Pragma Default_Scalar_Storage_Order:: -* Pragma Default_Storage_Pool:: -* Pragma Depends:: -* Pragma Detect_Blocking:: -* Pragma Disable_Atomic_Synchronization:: -* Pragma Dispatching_Domain:: -* Pragma Effective_Reads:: -* Pragma Effective_Writes:: -* Pragma Elaboration_Checks:: -* Pragma Eliminate:: -* Pragma Enable_Atomic_Synchronization:: -* Pragma Export_Function:: -* Pragma Export_Object:: -* Pragma Export_Procedure:: -* Pragma Export_Valued_Procedure:: -* Pragma Extend_System:: -* Pragma Extensions_Allowed:: -* Pragma Extensions_Visible:: -* Pragma External:: -* Pragma External_Name_Casing:: -* Pragma Fast_Math:: -* Pragma Favor_Top_Level:: -* Pragma Finalize_Storage_Only:: -* Pragma Float_Representation:: -* Pragma Ghost:: -* Pragma Global:: -* Pragma Ident:: -* Pragma Ignore_Pragma:: -* Pragma Implementation_Defined:: -* Pragma Implemented:: -* Pragma Implicit_Packing:: -* Pragma Import_Function:: -* Pragma Import_Object:: -* Pragma Import_Procedure:: -* Pragma Import_Valued_Procedure:: -* Pragma Independent:: -* Pragma Independent_Components:: -* Pragma Initial_Condition:: -* Pragma Initialize_Scalars:: -* Pragma Initializes:: -* Pragma Inline_Always:: -* Pragma Inline_Generic:: -* Pragma Interface:: -* Pragma Interface_Name:: -* Pragma Interrupt_Handler:: -* Pragma Interrupt_State:: -* Pragma Invariant:: -* Pragma Keep_Names:: -* Pragma License:: -* Pragma Link_With:: -* Pragma Linker_Alias:: -* Pragma Linker_Constructor:: -* Pragma Linker_Destructor:: -* Pragma Linker_Section:: -* Pragma Lock_Free:: -* Pragma Loop_Invariant:: -* Pragma Loop_Optimize:: -* Pragma Loop_Variant:: -* Pragma Machine_Attribute:: -* Pragma Main:: -* Pragma Main_Storage:: -* Pragma Max_Queue_Length:: -* Pragma No_Body:: -* Pragma No_Caching:: -* Pragma No_Component_Reordering:: -* Pragma No_Elaboration_Code_All:: -* Pragma No_Heap_Finalization:: -* Pragma No_Inline:: -* Pragma No_Return:: -* Pragma No_Strict_Aliasing:: -* Pragma No_Tagged_Streams:: -* Pragma Normalize_Scalars:: -* Pragma Obsolescent:: -* Pragma Optimize_Alignment:: -* Pragma Ordered:: -* Pragma Overflow_Mode:: -* Pragma Overriding_Renamings:: -* Pragma Partition_Elaboration_Policy:: -* Pragma Part_Of:: -* Pragma Passive:: -* Pragma Persistent_BSS:: -* Pragma Post:: -* Pragma Postcondition:: -* Pragma Post_Class:: -* Pragma Pre:: -* Pragma Precondition:: -* Pragma Predicate:: -* Pragma Predicate_Failure:: -* Pragma Preelaborable_Initialization:: -* Pragma Prefix_Exception_Messages:: -* Pragma Pre_Class:: -* Pragma Priority_Specific_Dispatching:: -* Pragma Profile:: -* Pragma Profile_Warnings:: -* Pragma Propagate_Exceptions:: -* Pragma Provide_Shift_Operators:: -* Pragma Psect_Object:: -* Pragma Pure_Function:: -* Pragma Rational:: -* Pragma Ravenscar:: -* Pragma Refined_Depends:: -* Pragma Refined_Global:: -* Pragma Refined_Post:: -* Pragma Refined_State:: -* Pragma Relative_Deadline:: -* Pragma Remote_Access_Type:: -* Pragma Rename_Pragma:: -* Pragma Restricted_Run_Time:: -* Pragma Restriction_Warnings:: -* Pragma Reviewable:: -* Pragma Secondary_Stack_Size:: -* Pragma Share_Generic:: -* Pragma Shared:: -* Pragma Short_Circuit_And_Or:: -* Pragma Short_Descriptors:: -* Pragma Simple_Storage_Pool_Type:: -* Pragma Source_File_Name:: -* Pragma Source_File_Name_Project:: -* Pragma Source_Reference:: -* Pragma SPARK_Mode:: -* Pragma Static_Elaboration_Desired:: -* Pragma Stream_Convert:: -* Pragma Style_Checks:: -* Pragma Subtitle:: -* Pragma Suppress:: -* Pragma Suppress_All:: -* Pragma Suppress_Debug_Info:: -* Pragma Suppress_Exception_Locations:: -* Pragma Suppress_Initialization:: -* Pragma Task_Name:: -* Pragma Task_Storage:: -* Pragma Test_Case:: -* Pragma Thread_Local_Storage:: -* Pragma Time_Slice:: -* Pragma Title:: -* Pragma Type_Invariant:: -* Pragma Type_Invariant_Class:: -* Pragma Unchecked_Union:: -* Pragma Unevaluated_Use_Of_Old:: -* Pragma Unimplemented_Unit:: -* Pragma Universal_Aliasing:: -* Pragma Unmodified:: -* Pragma Unreferenced:: -* Pragma Unreferenced_Objects:: -* Pragma Unreserve_All_Interrupts:: -* Pragma Unsuppress:: -* Pragma Use_VADS_Size:: -* Pragma Unused:: -* Pragma Validity_Checks:: -* Pragma Volatile:: -* Pragma Volatile_Full_Access:: -* Pragma Volatile_Function:: -* Pragma Warning_As_Error:: -* Pragma Warnings:: -* Pragma Weak_External:: -* Pragma Wide_Character_Encoding:: - -@end menu - -@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1c} -@section Pragma Abort_Defer - - -@geindex Deferring aborts - -Syntax: - -@example -pragma Abort_Defer; -@end example - -This pragma must appear at the start of the statement sequence of a -handled sequence of statements (right after the @code{begin}). It has -the effect of deferring aborts for the sequence of statements (but not -for the declarations or handlers, if any, associated with this statement -sequence). This can also be useful for adding a polling point in Ada code, -where asynchronous abort of tasks is checked when leaving the statement -sequence, and is lighter than, for example, using @code{delay 0.0;}, since with -zero-cost exception handling, propagating exceptions (implicitly used to -implement task abort) cannot be done reliably in an asynchronous way. - -An example of usage would be: - -@example --- Add a polling point to check for task aborts - -begin - pragma Abort_Defer; -end; -@end example - -@node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d}@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1e} -@section Pragma Abstract_State - - -Syntax: - -@example -pragma Abstract_State (ABSTRACT_STATE_LIST); - -ABSTRACT_STATE_LIST ::= - null - | STATE_NAME_WITH_OPTIONS - | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) - -STATE_NAME_WITH_OPTIONS ::= - STATE_NAME - | (STATE_NAME with OPTION_LIST) - -OPTION_LIST ::= OPTION @{, OPTION@} - -OPTION ::= - SIMPLE_OPTION - | NAME_VALUE_OPTION - -SIMPLE_OPTION ::= Ghost | Synchronous - -NAME_VALUE_OPTION ::= - Part_Of => ABSTRACT_STATE - | External [=> EXTERNAL_PROPERTY_LIST] - -EXTERNAL_PROPERTY_LIST ::= - EXTERNAL_PROPERTY - | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) - -EXTERNAL_PROPERTY ::= - Async_Readers [=> static_boolean_EXPRESSION] - | Async_Writers [=> static_boolean_EXPRESSION] - | Effective_Reads [=> static_boolean_EXPRESSION] - | Effective_Writes [=> static_boolean_EXPRESSION] - others => static_boolean_EXPRESSION - -STATE_NAME ::= defining_identifier - -ABSTRACT_STATE ::= name -@end example - -For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in -the SPARK 2014 Reference Manual, section 7.1.4. - -@node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1f} -@section Pragma Ada_83 - - -Syntax: - -@example -pragma Ada_83; -@end example - -A configuration pragma that establishes Ada 83 mode for the unit to -which it applies, regardless of the mode set by the command line -switches. In Ada 83 mode, GNAT attempts to be as compatible with -the syntax and semantics of Ada 83, as defined in the original Ada -83 Reference Manual as possible. In particular, the keywords added by Ada 95 -and Ada 2005 are not recognized, optional package bodies are allowed, -and generics may name types with unknown discriminants without using -the @code{(<>)} notation. In addition, some but not all of the additional -restrictions of Ada 83 are enforced. - -Ada 83 mode is intended for two purposes. Firstly, it allows existing -Ada 83 code to be compiled and adapted to GNAT with less effort. -Secondly, it aids in keeping code backwards compatible with Ada 83. -However, there is no guarantee that code that is processed correctly -by GNAT in Ada 83 mode will in fact compile and execute with an Ada -83 compiler, since GNAT does not enforce all the additional checks -required by Ada 83. - -@node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{20} -@section Pragma Ada_95 - - -Syntax: - -@example -pragma Ada_95; -@end example - -A configuration pragma that establishes Ada 95 mode for the unit to which -it applies, regardless of the mode set by the command line switches. -This mode is set automatically for the @code{Ada} and @code{System} -packages and their children, so you need not specify it in these -contexts. This pragma is useful when writing a reusable component that -itself uses Ada 95 features, but which is intended to be usable from -either Ada 83 or Ada 95 programs. - -@node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{21} -@section Pragma Ada_05 - - -Syntax: - -@example -pragma Ada_05; -pragma Ada_05 (local_NAME); -@end example - -A configuration pragma that establishes Ada 2005 mode for the unit to which -it applies, regardless of the mode set by the command line switches. -This pragma is useful when writing a reusable component that -itself uses Ada 2005 features, but which is intended to be usable from -either Ada 83 or Ada 95 programs. - -The one argument form (which is not a configuration pragma) -is used for managing the transition from -Ada 95 to Ada 2005 in the run-time library. If an entity is marked -as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 -mode will generate a warning. In addition, in Ada_83 or Ada_95 -mode, a preference rule is established which does not choose -such an entity unless it is unambiguously specified. This avoids -extra subprograms marked this way from generating ambiguities in -otherwise legal pre-Ada_2005 programs. The one argument form is -intended for exclusive use in the GNAT run-time library. - -@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{22} -@section Pragma Ada_2005 - - -Syntax: - -@example -pragma Ada_2005; -@end example - -This configuration pragma is a synonym for pragma Ada_05 and has the -same syntax and effect. - -@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{23} -@section Pragma Ada_12 - - -Syntax: - -@example -pragma Ada_12; -pragma Ada_12 (local_NAME); -@end example - -A configuration pragma that establishes Ada 2012 mode for the unit to which -it applies, regardless of the mode set by the command line switches. -This mode is set automatically for the @code{Ada} and @code{System} -packages and their children, so you need not specify it in these -contexts. This pragma is useful when writing a reusable component that -itself uses Ada 2012 features, but which is intended to be usable from -Ada 83, Ada 95, or Ada 2005 programs. - -The one argument form, which is not a configuration pragma, -is used for managing the transition from Ada -2005 to Ada 2012 in the run-time library. If an entity is marked -as Ada_2012 only, then referencing the entity in any pre-Ada_2012 -mode will generate a warning. In addition, in any pre-Ada_2012 -mode, a preference rule is established which does not choose -such an entity unless it is unambiguously specified. This avoids -extra subprograms marked this way from generating ambiguities in -otherwise legal pre-Ada_2012 programs. The one argument form is -intended for exclusive use in the GNAT run-time library. - -@node Pragma Ada_2012,Pragma Ada_2022,Pragma Ada_12,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{24} -@section Pragma Ada_2012 - - -Syntax: - -@example -pragma Ada_2012; -@end example - -This configuration pragma is a synonym for pragma Ada_12 and has the -same syntax and effect. - -@node Pragma Ada_2022,Pragma Aggregate_Individually_Assign,Pragma Ada_2012,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2022}@anchor{25} -@section Pragma Ada_2022 - - -Syntax: - -@example -pragma Ada_2022; -pragma Ada_2022 (local_NAME); -@end example - -A configuration pragma that establishes Ada 2022 mode for the unit to which -it applies, regardless of the mode set by the command line switches. -This mode is set automatically for the @code{Ada} and @code{System} -packages and their children, so you need not specify it in these -contexts. This pragma is useful when writing a reusable component that -itself uses Ada 2022 features, but which is intended to be usable from -Ada 83, Ada 95, Ada 2005 or Ada 2012 programs. - -The one argument form, which is not a configuration pragma, -is used for managing the transition from Ada -2012 to Ada 2022 in the run-time library. If an entity is marked -as Ada_2022 only, then referencing the entity in any pre-Ada_2022 -mode will generate a warning. In addition, in any pre-Ada_2012 -mode, a preference rule is established which does not choose -such an entity unless it is unambiguously specified. This avoids -extra subprograms marked this way from generating ambiguities in -otherwise legal pre-Ada_2022 programs. The one argument form is -intended for exclusive use in the GNAT run-time library. - -@node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2022,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{26} -@section Pragma Aggregate_Individually_Assign - - -Syntax: - -@example -pragma Aggregate_Individually_Assign; -@end example - -Where possible, GNAT will store the binary representation of a record aggregate -in memory for space and performance reasons. This configuration pragma changes -this behavior so that record aggregates are instead always converted into -individual assignment statements. - -@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{27} -@section Pragma Allow_Integer_Address - - -Syntax: - -@example -pragma Allow_Integer_Address; -@end example - -In almost all versions of GNAT, @code{System.Address} is a private -type in accordance with the implementation advice in the RM. This -means that integer values, -in particular integer literals, are not allowed as address values. -If the configuration pragma -@code{Allow_Integer_Address} is given, then integer expressions may -be used anywhere a value of type @code{System.Address} is required. -The effect is to introduce an implicit unchecked conversion from the -integer value to type @code{System.Address}. The reverse case of using -an address where an integer type is required is handled analogously. -The following example compiles without errors: - -@example -pragma Allow_Integer_Address; -with System; use System; -package AddrAsInt is - X : Integer; - Y : Integer; - for X'Address use 16#1240#; - for Y use at 16#3230#; - m : Address := 16#4000#; - n : constant Address := 4000; - p : constant Address := Address (X + Y); - v : Integer := y'Address; - w : constant Integer := Integer (Y'Address); - type R is new integer; - RR : R := 1000; - Z : Integer; - for Z'Address use RR; -end AddrAsInt; -@end example - -Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address} -is not a private type. In implementations of @code{GNAT} where -System.Address is a visible integer type, -this pragma serves no purpose but is ignored -rather than rejected to allow common sets of sources to be used -in the two situations. - -@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{28}@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{29} -@section Pragma Annotate - - -Syntax: - -@example -pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); - -ARG ::= NAME | EXPRESSION -@end example - -This pragma is used to annotate programs. IDENTIFIER identifies -the type of annotation. GNAT verifies that it is an identifier, but does -not otherwise analyze it. The second optional identifier is also left -unanalyzed, and by convention is used to control the action of the tool to -which the annotation is addressed. The remaining ARG arguments -can be either string literals or more generally expressions. -String literals (and concatenations of string literals) are assumed to be -either of type -@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} -depending on the character literals they contain. -All other kinds of arguments are analyzed as expressions, and must be -unambiguous. The last argument if present must have the identifier -@code{Entity} and GNAT verifies that a local name is given. - -The analyzed pragma is retained in the tree, but not otherwise processed -by any part of the GNAT compiler, except to generate corresponding note -lines in the generated ALI file. For the format of these note lines, see -the compiler source file lib-writ.ads. This pragma is intended for use by -external tools, including ASIS. The use of pragma Annotate does not -affect the compilation process in any way. This pragma may be used as -a configuration pragma. - -@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{2a} -@section Pragma Assert - - -Syntax: - -@example -pragma Assert ( - boolean_EXPRESSION - [, string_EXPRESSION]); -@end example - -The effect of this pragma depends on whether the corresponding command -line switch is set to activate assertions. The pragma expands into code -equivalent to the following: - -@example -if assertions-enabled then - if not boolean_EXPRESSION then - System.Assertions.Raise_Assert_Failure - (string_EXPRESSION); - end if; -end if; -@end example - -The string argument, if given, is the message that will be associated -with the exception occurrence if the exception is raised. If no second -argument is given, the default message is @code{file}:@code{nnn}, -where @code{file} is the name of the source file containing the assert, -and @code{nnn} is the line number of the assert. - -Note that, as with the @code{if} statement to which it is equivalent, the -type of the expression is either @code{Standard.Boolean}, or any type derived -from this standard type. - -Assert checks can be either checked or ignored. By default they are ignored. -They will be checked if either the command line switch `-gnata' is -used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used -to enable @code{Assert_Checks}. - -If assertions are ignored, then there -is no run-time effect (and in particular, any side effects from the -expression will not occur at run time). (The expression is still -analyzed at compile time, and may cause types to be frozen if they are -mentioned here for the first time). - -If assertions are checked, then the given expression is tested, and if -it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called -which results in the raising of @code{Assert_Failure} with the given message. - -You should generally avoid side effects in the expression arguments of -this pragma, because these side effects will turn on and off with the -setting of the assertions mode, resulting in assertions that have an -effect on the program. However, the expressions are analyzed for -semantic correctness whether or not assertions are enabled, so turning -assertions on and off cannot affect the legality of a program. - -Note that the implementation defined policy @code{DISABLE}, given in a -pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. - -Note: this is a standard language-defined pragma in versions -of Ada from 2005 on. In GNAT, it is implemented in all versions -of Ada, and the DISABLE policy is an implementation-defined -addition. - -@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2b} -@section Pragma Assert_And_Cut - - -Syntax: - -@example -pragma Assert_And_Cut ( - boolean_EXPRESSION - [, string_EXPRESSION]); -@end example - -The effect of this pragma is identical to that of pragma @code{Assert}, -except that in an @code{Assertion_Policy} pragma, the identifier -@code{Assert_And_Cut} is used to control whether it is ignored or checked -(or disabled). - -The intention is that this be used within a subprogram when the -given test expresion sums up all the work done so far in the -subprogram, so that the rest of the subprogram can be verified -(informally or formally) using only the entry preconditions, -and the expression in this pragma. This allows dividing up -a subprogram into sections for the purposes of testing or -formal verification. The pragma also serves as useful -documentation. - -@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2c} -@section Pragma Assertion_Policy - - -Syntax: - -@example -pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); - -pragma Assertion_Policy ( - ASSERTION_KIND => POLICY_IDENTIFIER - @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); - -ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND - -RM_ASSERTION_KIND ::= Assert | - Static_Predicate | - Dynamic_Predicate | - Pre | - Pre'Class | - Post | - Post'Class | - Type_Invariant | - Type_Invariant'Class | - Default_Initial_Condition - -ID_ASSERTION_KIND ::= Assertions | - Assert_And_Cut | - Assume | - Contract_Cases | - Debug | - Ghost | - Initial_Condition | - Invariant | - Invariant'Class | - Loop_Invariant | - Loop_Variant | - Postcondition | - Precondition | - Predicate | - Refined_Post | - Statement_Assertions | - Subprogram_Variant - -POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible -@end example - -This is a standard Ada 2012 pragma that is available as an -implementation-defined pragma in earlier versions of Ada. -The assertion kinds @code{RM_ASSERTION_KIND} are those defined in -the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} -are implementation defined additions recognized by the GNAT compiler. - -The pragma applies in both cases to pragmas and aspects with matching -names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} -applies to both the @code{Precondition} pragma -and the aspect @code{Precondition}. Note that the identifiers for -pragmas Pre_Class and Post_Class are Pre’Class and Post’Class (not -Pre_Class and Post_Class), since these pragmas are intended to be -identical to the corresponding aspects. - -If the policy is @code{CHECK}, then assertions are enabled, i.e. -the corresponding pragma or aspect is activated. -If the policy is @code{IGNORE}, then assertions are ignored, i.e. -the corresponding pragma or aspect is deactivated. -This pragma overrides the effect of the `-gnata' switch on the -command line. -If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default, -however, if the `-gnatp' switch is specified all assertions are ignored. - -The implementation defined policy @code{DISABLE} is like -@code{IGNORE} except that it completely disables semantic -checking of the corresponding pragma or aspect. This is -useful when the pragma or aspect argument references subprograms -in a with’ed package which is replaced by a dummy package -for the final build. - -The implementation defined assertion kind @code{Assertions} applies to all -assertion kinds. The form with no assertion kind given implies this -choice, so it applies to all assertion kinds (RM defined, and -implementation defined). - -The implementation defined assertion kind @code{Statement_Assertions} -applies to @code{Assert}, @code{Assert_And_Cut}, -@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. - -@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2d} -@section Pragma Assume - - -Syntax: - -@example -pragma Assume ( - boolean_EXPRESSION - [, string_EXPRESSION]); -@end example - -The effect of this pragma is identical to that of pragma @code{Assert}, -except that in an @code{Assertion_Policy} pragma, the identifier -@code{Assume} is used to control whether it is ignored or checked -(or disabled). - -The intention is that this be used for assumptions about the -external environment. So you cannot expect to verify formally -or informally that the condition is met, this must be -established by examining things outside the program itself. -For example, we may have code that depends on the size of -@code{Long_Long_Integer} being at least 64. So we could write: - -@example -pragma Assume (Long_Long_Integer'Size >= 64); -@end example - -This assumption cannot be proved from the program itself, -but it acts as a useful run-time check that the assumption -is met, and documents the need to ensure that it is met by -reference to information outside the program. - -@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2e} -@section Pragma Assume_No_Invalid_Values - - -@geindex Invalid representations - -@geindex Invalid values - -Syntax: - -@example -pragma Assume_No_Invalid_Values (On | Off); -@end example - -This is a configuration pragma that controls the assumptions made by the -compiler about the occurrence of invalid representations (invalid values) -in the code. - -The default behavior (corresponding to an Off argument for this pragma), is -to assume that values may in general be invalid unless the compiler can -prove they are valid. Consider the following example: - -@example -V1 : Integer range 1 .. 10; -V2 : Integer range 11 .. 20; -... -for J in V2 .. V1 loop - ... -end loop; -@end example - -if V1 and V2 have valid values, then the loop is known at compile -time not to execute since the lower bound must be greater than the -upper bound. However in default mode, no such assumption is made, -and the loop may execute. If @code{Assume_No_Invalid_Values (On)} -is given, the compiler will assume that any occurrence of a variable -other than in an explicit @code{'Valid} test always has a valid -value, and the loop above will be optimized away. - -The use of @code{Assume_No_Invalid_Values (On)} is appropriate if -you know your code is free of uninitialized variables and other -possible sources of invalid representations, and may result in -more efficient code. A program that accesses an invalid representation -with this pragma in effect is erroneous, so no guarantees can be made -about its behavior. - -It is peculiar though permissible to use this pragma in conjunction -with validity checking (-gnatVa). In such cases, accessing invalid -values will generally give an exception, though formally the program -is erroneous so there are no guarantees that this will always be the -case, and it is recommended that these two options not be used together. - -@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2f}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{30} -@section Pragma Async_Readers - - -Syntax: - -@example -pragma Async_Readers [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in -the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{31}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{32} -@section Pragma Async_Writers - - -Syntax: - -@example -pragma Async_Writers [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in -the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{33} -@section Pragma Attribute_Definition - - -Syntax: - -@example -pragma Attribute_Definition - ([Attribute =>] ATTRIBUTE_DESIGNATOR, - [Entity =>] LOCAL_NAME, - [Expression =>] EXPRESSION | NAME); -@end example - -If @code{Attribute} is a known attribute name, this pragma is equivalent to -the attribute definition clause: - -@example -for Entity'Attribute use Expression; -@end example - -If @code{Attribute} is not a recognized attribute name, the pragma is -ignored, and a warning is emitted. This allows source -code to be written that takes advantage of some new attribute, while remaining -compilable with earlier compilers. - -@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{34} -@section Pragma C_Pass_By_Copy - - -@geindex Passing by copy - -Syntax: - -@example -pragma C_Pass_By_Copy - ([Max_Size =>] static_integer_EXPRESSION); -@end example - -Normally the default mechanism for passing C convention records to C -convention subprograms is to pass them by reference, as suggested by RM -B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change -this default, by requiring that record formal parameters be passed by -copy if all of the following conditions are met: - - -@itemize * - -@item -The size of the record type does not exceed the value specified for -@code{Max_Size}. - -@item -The record type has @code{Convention C}. - -@item -The formal parameter has this record type, and the subprogram has a -foreign (non-Ada) convention. -@end itemize - -If these conditions are met the argument is passed by copy; i.e., in a -manner consistent with what C expects if the corresponding formal in the -C prototype is a struct (rather than a pointer to a struct). - -You can also pass records by copy by specifying the convention -@code{C_Pass_By_Copy} for the record type, or by using the extended -@code{Import} and @code{Export} pragmas, which allow specification of -passing mechanisms on a parameter by parameter basis. - -@node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{35} -@section Pragma Check - - -@geindex Assertions - -@geindex Named assertions - -Syntax: - -@example -pragma Check ( - [Name =>] CHECK_KIND, - [Check =>] Boolean_EXPRESSION - [, [Message =>] string_EXPRESSION] ); - -CHECK_KIND ::= IDENTIFIER | - Pre'Class | - Post'Class | - Type_Invariant'Class | - Invariant'Class -@end example - -This pragma is similar to the predefined pragma @code{Assert} except that an -extra identifier argument is present. In conjunction with pragma -@code{Check_Policy}, this can be used to define groups of assertions that can -be independently controlled. The identifier @code{Assertion} is special, it -refers to the normal set of pragma @code{Assert} statements. - -Checks introduced by this pragma are normally deactivated by default. They can -be activated either by the command line option `-gnata', which turns on -all checks, or individually controlled using pragma @code{Check_Policy}. - -The identifiers @code{Assertions} and @code{Statement_Assertions} are not -permitted as check kinds, since this would cause confusion with the use -of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} -pragmas, where they are used to refer to sets of assertions. - -@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{36} -@section Pragma Check_Float_Overflow - - -@geindex Floating-point overflow - -Syntax: - -@example -pragma Check_Float_Overflow; -@end example - -In Ada, the predefined floating-point types (@code{Short_Float}, -@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are -defined to be `unconstrained'. This means that even though each -has a well-defined base range, an operation that delivers a result -outside this base range is not required to raise an exception. -This implementation permission accommodates the notion -of infinities in IEEE floating-point, and corresponds to the -efficient execution mode on most machines. GNAT will not raise -overflow exceptions on these machines; instead it will generate -infinities and NaN’s as defined in the IEEE standard. - -Generating infinities, although efficient, is not always desirable. -Often the preferable approach is to check for overflow, even at the -(perhaps considerable) expense of run-time performance. -This can be accomplished by defining your own constrained floating-point subtypes – i.e., by supplying explicit -range constraints – and indeed such a subtype -can have the same base range as its base type. For example: - -@example -subtype My_Float is Float range Float'Range; -@end example - -Here @code{My_Float} has the same range as -@code{Float} but is constrained, so operations on -@code{My_Float} values will be checked for overflow -against this range. - -This style will achieve the desired goal, but -it is often more convenient to be able to simply use -the standard predefined floating-point types as long -as overflow checking could be guaranteed. -The @code{Check_Float_Overflow} -configuration pragma achieves this effect. If a unit is compiled -subject to this configuration pragma, then all operations -on predefined floating-point types including operations on -base types of these floating-point types will be treated as -though those types were constrained, and overflow checks -will be generated. The @code{Constraint_Error} -exception is raised if the result is out of range. - -This mode can also be set by use of the compiler -switch `-gnateF'. - -@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{37} -@section Pragma Check_Name - - -@geindex Defining check names - -@geindex Check names -@geindex defining - -Syntax: - -@example -pragma Check_Name (check_name_IDENTIFIER); -@end example - -This is a configuration pragma that defines a new implementation -defined check name (unless IDENTIFIER matches one of the predefined -check names, in which case the pragma has no effect). Check names -are global to a partition, so if two or more configuration pragmas -are present in a partition mentioning the same name, only one new -check name is introduced. - -An implementation defined check name introduced with this pragma may -be used in only three contexts: @code{pragma Suppress}, -@code{pragma Unsuppress}, -and as the prefix of a @code{Check_Name'Enabled} attribute reference. For -any of these three cases, the check name must be visible. A check -name is visible if it is in the configuration pragmas applying to -the current unit, or if it appears at the start of any unit that -is part of the dependency set of the current unit (e.g., units that -are mentioned in @code{with} clauses). - -Check names introduced by this pragma are subject to control by compiler -switches (in particular -gnatp) in the usual manner. - -@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{38} -@section Pragma Check_Policy - - -@geindex Controlling assertions - -@geindex Assertions -@geindex control - -@geindex Check pragma control - -@geindex Named assertions - -Syntax: - -@example -pragma Check_Policy - ([Name =>] CHECK_KIND, - [Policy =>] POLICY_IDENTIFIER); - -pragma Check_Policy ( - CHECK_KIND => POLICY_IDENTIFIER - @{, CHECK_KIND => POLICY_IDENTIFIER@}); - -ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND - -CHECK_KIND ::= IDENTIFIER | - Pre'Class | - Post'Class | - Type_Invariant'Class | - Invariant'Class - -The identifiers Name and Policy are not allowed as CHECK_KIND values. This -avoids confusion between the two possible syntax forms for this pragma. - -POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE -@end example - -This pragma is used to set the checking policy for assertions (specified -by aspects or pragmas), the @code{Debug} pragma, or additional checks -to be checked using the @code{Check} pragma. It may appear either as -a configuration pragma, or within a declarative part of package. In the -latter case, it applies from the point where it appears to the end of -the declarative region (like pragma @code{Suppress}). - -The @code{Check_Policy} pragma is similar to the -predefined @code{Assertion_Policy} pragma, -and if the check kind corresponds to one of the assertion kinds that -are allowed by @code{Assertion_Policy}, then the effect is identical. - -If the first argument is Debug, then the policy applies to Debug pragmas, -disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or -@code{IGNORE}, and allowing them to execute with normal semantics if -the policy is @code{ON} or @code{CHECK}. In addition if the policy is -@code{DISABLE}, then the procedure call in @code{Debug} pragmas will -be totally ignored and not analyzed semantically. - -Finally the first argument may be some other identifier than the above -possibilities, in which case it controls a set of named assertions -that can be checked using pragma @code{Check}. For example, if the pragma: - -@example -pragma Check_Policy (Critical_Error, OFF); -@end example - -is given, then subsequent @code{Check} pragmas whose first argument is also -@code{Critical_Error} will be disabled. - -The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} -to turn on corresponding checks. The default for a set of checks for which no -@code{Check_Policy} is given is @code{OFF} unless the compiler switch -`-gnata' is given, which turns on all checks by default. - -The check policy settings @code{CHECK} and @code{IGNORE} are recognized -as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for -compatibility with the standard @code{Assertion_Policy} pragma. The check -policy setting @code{DISABLE} causes the second argument of a corresponding -@code{Check} pragma to be completely ignored and not analyzed. - -@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{39} -@section Pragma Comment - - -Syntax: - -@example -pragma Comment (static_string_EXPRESSION); -@end example - -This is almost identical in effect to pragma @code{Ident}. It allows the -placement of a comment into the object file and hence into the -executable file if the operating system permits such usage. The -difference is that @code{Comment}, unlike @code{Ident}, has -no limitations on placement of the pragma (it can be placed -anywhere in the main source unit), and if more than one pragma -is used, all comments are retained. - -@node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{3a} -@section Pragma Common_Object - - -Syntax: - -@example -pragma Common_Object ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL] ); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -@end example - -This pragma enables the shared use of variables stored in overlaid -linker areas corresponding to the use of @code{COMMON} -in Fortran. The single -object @code{LOCAL_NAME} is assigned to the area designated by -the @code{External} argument. -You may define a record to correspond to a series -of fields. The @code{Size} argument -is syntax checked in GNAT, but otherwise ignored. - -@code{Common_Object} is not supported on all platforms. If no -support is available, then the code generator will issue a message -indicating that the necessary attribute for implementation of this -pragma is not available. - -@node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas compile-time-error}@anchor{3b}@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3c} -@section Pragma Compile_Time_Error - - -Syntax: - -@example -pragma Compile_Time_Error - (boolean_EXPRESSION, static_string_EXPRESSION); -@end example - -This pragma can be used to generate additional compile time -error messages. It -is particularly useful in generics, where errors can be issued for -specific problematic instantiations. The first parameter is a boolean -expression. The pragma ensures that the value of an expression -is known at compile time, and has the value False. The set of expressions -whose values are known at compile time includes all static boolean -expressions, and also other values which the compiler can determine -at compile time (e.g., the size of a record type set by an explicit -size representation clause, or the value of a variable which was -initialized to a constant and is known not to have been modified). -If these conditions are not met, an error message is generated using -the value given as the second argument. This string value may contain -embedded ASCII.LF characters to break the message into multiple lines. - -@node Pragma Compile_Time_Warning,Pragma Complete_Representation,Pragma Compile_Time_Error,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3d} -@section Pragma Compile_Time_Warning - - -Syntax: - -@example -pragma Compile_Time_Warning - (boolean_EXPRESSION, static_string_EXPRESSION); -@end example - -Same as pragma Compile_Time_Error, except a warning is issued instead -of an error message. If switch `-gnatw_C' is used, a warning is only issued -if the value of the expression is known to be True at compile time, not when -the value of the expression is not known at compile time. -Note that if this pragma is used in a package that -is with’ed by a client, the client will get the warning even though it -is issued by a with’ed package (normally warnings in with’ed units are -suppressed, but this is a special exception to that rule). - -One typical use is within a generic where compile time known characteristics -of formal parameters are tested, and warnings given appropriately. Another use -with a first parameter of True is to warn a client about use of a package, -for example that it is not fully implemented. - -In previous versions of the compiler, combining `-gnatwe' with -Compile_Time_Warning resulted in a fatal error. Now the compiler always emits -a warning. You can use @ref{3b,,Pragma Compile_Time_Error} to force the generation of -an error. - -@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compile_Time_Warning,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3e} -@section Pragma Complete_Representation - - -Syntax: - -@example -pragma Complete_Representation; -@end example - -This pragma must appear immediately within a record representation -clause. Typical placements are before the first component clause -or after the last component clause. The effect is to give an error -message if any component is missing a component clause. This pragma -may be used to ensure that a record representation clause is -complete, and that this invariant is maintained if fields are -added to the record in the future. - -@node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{3f} -@section Pragma Complex_Representation - - -Syntax: - -@example -pragma Complex_Representation - ([Entity =>] LOCAL_NAME); -@end example - -The @code{Entity} argument must be the name of a record type which has -two fields of the same floating-point type. The effect of this pragma is -to force gcc to use the special internal complex representation form for -this record, which may be more efficient. Note that this may result in -the code for this type not conforming to standard ABI (application -binary interface) requirements for the handling of record types. For -example, in some environments, there is a requirement for passing -records by pointer, and the use of this pragma may result in passing -this type in floating-point registers. - -@node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{40} -@section Pragma Component_Alignment - - -@geindex Alignments of components - -@geindex Pragma Component_Alignment - -Syntax: - -@example -pragma Component_Alignment ( - [Form =>] ALIGNMENT_CHOICE - [, [Name =>] type_LOCAL_NAME]); - -ALIGNMENT_CHOICE ::= - Component_Size -| Component_Size_4 -| Storage_Unit -| Default -@end example - -Specifies the alignment of components in array or record types. -The meaning of the @code{Form} argument is as follows: - -@quotation - -@geindex Component_Size (in pragma Component_Alignment) -@end quotation - - -@table @asis - -@item `Component_Size' - -Aligns scalar components and subcomponents of the array or record type -on boundaries appropriate to their inherent size (naturally -aligned). For example, 1-byte components are aligned on byte boundaries, -2-byte integer components are aligned on 2-byte boundaries, 4-byte -integer components are aligned on 4-byte boundaries and so on. These -alignment rules correspond to the normal rules for C compilers on all -machines except the VAX. - -@geindex Component_Size_4 (in pragma Component_Alignment) - -@item `Component_Size_4' - -Naturally aligns components with a size of four or fewer -bytes. Components that are larger than 4 bytes are placed on the next -4-byte boundary. - -@geindex Storage_Unit (in pragma Component_Alignment) - -@item `Storage_Unit' - -Specifies that array or record components are byte aligned, i.e., -aligned on boundaries determined by the value of the constant -@code{System.Storage_Unit}. - -@geindex Default (in pragma Component_Alignment) - -@item `Default' - -Specifies that array or record components are aligned on default -boundaries, appropriate to the underlying hardware or operating system or -both. The @code{Default} choice is the same as @code{Component_Size} (natural -alignment). -@end table - -If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must -refer to a local record or array type, and the specified alignment -choice applies to the specified type. The use of -@code{Component_Alignment} together with a pragma @code{Pack} causes the -@code{Component_Alignment} pragma to be ignored. The use of -@code{Component_Alignment} together with a record representation clause -is only effective for fields not specified by the representation clause. - -If the @code{Name} parameter is absent, the pragma can be used as either -a configuration pragma, in which case it applies to one or more units in -accordance with the normal rules for configuration pragmas, or it can be -used within a declarative part, in which case it applies to types that -are declared within this declarative part, or within any nested scope -within this declarative part. In either case it specifies the alignment -to be applied to any record or array type which has otherwise standard -representation. - -If the alignment for a record or array type is not specified (using -pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep -clause), the GNAT uses the default alignment as described previously. - -@node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{41}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{42} -@section Pragma Constant_After_Elaboration - - -Syntax: - -@example -pragma Constant_After_Elaboration [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect -@code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. - -@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{43}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{44} -@section Pragma Contract_Cases - - -@geindex Contract cases - -Syntax: - -@example -pragma Contract_Cases (CONTRACT_CASE @{, CONTRACT_CASE@}); - -CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE - -CASE_GUARD ::= boolean_EXPRESSION | others - -CONSEQUENCE ::= boolean_EXPRESSION -@end example - -The @code{Contract_Cases} pragma allows defining fine-grain specifications -that can complement or replace the contract given by a precondition and a -postcondition. Additionally, the @code{Contract_Cases} pragma can be used -by testing and formal verification tools. The compiler checks its validity and, -depending on the assertion policy at the point of declaration of the pragma, -it may insert a check in the executable. For code generation, the contract -cases - -@example -pragma Contract_Cases ( - Cond1 => Pred1, - Cond2 => Pred2); -@end example - -are equivalent to - -@example -C1 : constant Boolean := Cond1; -- evaluated at subprogram entry -C2 : constant Boolean := Cond2; -- evaluated at subprogram entry -pragma Precondition ((C1 and not C2) or (C2 and not C1)); -pragma Postcondition (if C1 then Pred1); -pragma Postcondition (if C2 then Pred2); -@end example - -The precondition ensures that one and only one of the case guards is -satisfied on entry to the subprogram. -The postcondition ensures that for the case guard that was True on entry, -the corresponding consequence is True on exit. Other consequence expressions -are not evaluated. - -A precondition @code{P} and postcondition @code{Q} can also be -expressed as contract cases: - -@example -pragma Contract_Cases (P => Q); -@end example - -The placement and visibility rules for @code{Contract_Cases} pragmas are -identical to those described for preconditions and postconditions. - -The compiler checks that boolean expressions given in case guards and -consequences are valid, where the rules for case guards are the same as -the rule for an expression in @code{Precondition} and the rules for -consequences are the same as the rule for an expression in -@code{Postcondition}. In particular, attributes @code{'Old} and -@code{'Result} can only be used within consequence expressions. -The case guard for the last contract case may be @code{others}, to denote -any case not captured by the previous cases. The -following is an example of use within a package spec: - -@example -package Math_Functions is - ... - function Sqrt (Arg : Float) return Float; - pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, - Arg >= 100.0 => Sqrt'Result >= 10.0, - others => Sqrt'Result = 0.0)); - ... -end Math_Functions; -@end example - -The meaning of contract cases is that only one case should apply at each -call, as determined by the corresponding case guard evaluating to True, -and that the consequence for this case should hold when the subprogram -returns. - -@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{45} -@section Pragma Convention_Identifier - - -@geindex Conventions -@geindex synonyms - -Syntax: - -@example -pragma Convention_Identifier ( - [Name =>] IDENTIFIER, - [Convention =>] convention_IDENTIFIER); -@end example - -This pragma provides a mechanism for supplying synonyms for existing -convention identifiers. The @code{Name} identifier can subsequently -be used as a synonym for the given convention in other pragmas (including -for example pragma @code{Import} or another @code{Convention_Identifier} -pragma). As an example of the use of this, suppose you had legacy code -which used Fortran77 as the identifier for Fortran. Then the pragma: - -@example -pragma Convention_Identifier (Fortran77, Fortran); -@end example - -would allow the use of the convention identifier @code{Fortran77} in -subsequent code, avoiding the need to modify the sources. As another -example, you could use this to parameterize convention requirements -according to systems. Suppose you needed to use @code{Stdcall} on -windows systems, and @code{C} on some other system, then you could -define a convention identifier @code{Library} and use a single -@code{Convention_Identifier} pragma to specify which convention -would be used system-wide. - -@node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{46} -@section Pragma CPP_Class - - -@geindex Interfacing with C++ - -Syntax: - -@example -pragma CPP_Class ([Entity =>] LOCAL_NAME); -@end example - -The argument denotes an entity in the current declarative region that is -declared as a record type. It indicates that the type corresponds to an -externally declared C++ class type, and is to be laid out the same way -that C++ would lay out the type. If the C++ class has virtual primitives -then the record must be declared as a tagged record type. - -Types for which @code{CPP_Class} is specified do not have assignment or -equality operators defined (such operations can be imported or declared -as subprograms as required). Initialization is allowed only by constructor -functions (see pragma @code{CPP_Constructor}). Such types are implicitly -limited if not explicitly declared as limited or derived from a limited -type, and an error is issued in that case. - -See @ref{47,,Interfacing to C++} for related information. - -Note: Pragma @code{CPP_Class} is currently obsolete. It is supported -for backward compatibility but its functionality is available -using pragma @code{Import} with @code{Convention} = @code{CPP}. - -@node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{48} -@section Pragma CPP_Constructor - - -@geindex Interfacing with C++ - -Syntax: - -@example -pragma CPP_Constructor ([Entity =>] LOCAL_NAME - [, [External_Name =>] static_string_EXPRESSION ] - [, [Link_Name =>] static_string_EXPRESSION ]); -@end example - -This pragma identifies an imported function (imported in the usual way -with pragma @code{Import}) as corresponding to a C++ constructor. If -@code{External_Name} and @code{Link_Name} are not specified then the -@code{Entity} argument is a name that must have been previously mentioned -in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name -must be of one of the following forms: - - -@itemize * - -@item -`function' @code{Fname} `return' T` - -@item -`function' @code{Fname} `return' T’Class - -@item -`function' @code{Fname} (…) `return' T` - -@item -`function' @code{Fname} (…) `return' T’Class -@end itemize - -where @code{T} is a limited record type imported from C++ with pragma -@code{Import} and @code{Convention} = @code{CPP}. - -The first two forms import the default constructor, used when an object -of type @code{T} is created on the Ada side with no explicit constructor. -The latter two forms cover all the non-default constructors of the type. -See the GNAT User’s Guide for details. - -If no constructors are imported, it is impossible to create any objects -on the Ada side and the type is implicitly declared abstract. - -Pragma @code{CPP_Constructor} is intended primarily for automatic generation -using an automatic binding generator tool (such as the @code{-fdump-ada-spec} -GCC switch). -See @ref{47,,Interfacing to C++} for more related information. - -Note: The use of functions returning class-wide types for constructors is -currently obsolete. They are supported for backward compatibility. The -use of functions returning the type T leave the Ada sources more clear -because the imported C++ constructors always return an object of type T; -that is, they never return an object whose type is a descendant of type T. - -@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{49} -@section Pragma CPP_Virtual - - -@geindex Interfacing to C++ - -This pragma is now obsolete and, other than generating a warning if warnings -on obsolescent features are enabled, is completely ignored. -It is retained for compatibility -purposes. It used to be required to ensure compatibility with C++, but -is no longer required for that purpose because GNAT generates -the same object layout as the G++ compiler by default. - -See @ref{47,,Interfacing to C++} for related information. - -@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4a} -@section Pragma CPP_Vtable - - -@geindex Interfacing with C++ - -This pragma is now obsolete and, other than generating a warning if warnings -on obsolescent features are enabled, is completely ignored. -It used to be required to ensure compatibility with C++, but -is no longer required for that purpose because GNAT generates -the same object layout as the G++ compiler by default. - -See @ref{47,,Interfacing to C++} for related information. - -@node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4b} -@section Pragma CPU - - -Syntax: - -@example -pragma CPU (EXPRESSION); -@end example - -This pragma is standard in Ada 2012, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4c} -@section Pragma Deadline_Floor - - -Syntax: - -@example -pragma Deadline_Floor (time_span_EXPRESSION); -@end example - -This pragma applies only to protected types and specifies the floor -deadline inherited by a task when the task enters a protected object. -It is effective only when the EDF scheduling policy is used. - -@node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4d}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{4e} -@section Pragma Default_Initial_Condition - - -Syntax: - -@example -pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect -@code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. - -@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{4f} -@section Pragma Debug - - -Syntax: - -@example -pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); - -PROCEDURE_CALL_WITHOUT_SEMICOLON ::= - PROCEDURE_NAME -| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART -@end example - -The procedure call argument has the syntactic form of an expression, meeting -the syntactic requirements for pragmas. - -If debug pragmas are not enabled or if the condition is present and evaluates -to False, this pragma has no effect. If debug pragmas are enabled, the -semantics of the pragma is exactly equivalent to the procedure call statement -corresponding to the argument with a terminating semicolon. Pragmas are -permitted in sequences of declarations, so you can use pragma @code{Debug} to -intersperse calls to debug procedures in the middle of declarations. Debug -pragmas can be enabled either by use of the command line switch `-gnata' -or by use of the pragma @code{Check_Policy} with a first argument of -@code{Debug}. - -@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{50} -@section Pragma Debug_Policy - - -Syntax: - -@example -pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); -@end example - -This pragma is equivalent to a corresponding @code{Check_Policy} pragma -with a first argument of @code{Debug}. It is retained for historical -compatibility reasons. - -@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{51} -@section Pragma Default_Scalar_Storage_Order - - -@geindex Default_Scalar_Storage_Order - -@geindex Scalar_Storage_Order - -Syntax: - -@example -pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); -@end example - -Normally if no explicit @code{Scalar_Storage_Order} is given for a record -type or array type, then the scalar storage order defaults to the ordinary -default for the target. But this default may be overridden using this pragma. -The pragma may appear as a configuration pragma, or locally within a package -spec or declarative part. In the latter case, it applies to all subsequent -types declared within that package spec or declarative part. - -The following example shows the use of this pragma: - -@example -pragma Default_Scalar_Storage_Order (High_Order_First); -with System; use System; -package DSSO1 is - type H1 is record - a : Integer; - end record; - - type L2 is record - a : Integer; - end record; - for L2'Scalar_Storage_Order use Low_Order_First; - - type L2a is new L2; - - package Inner is - type H3 is record - a : Integer; - end record; - - pragma Default_Scalar_Storage_Order (Low_Order_First); - - type L4 is record - a : Integer; - end record; - end Inner; - - type H4a is new Inner.L4; - - type H5 is record - a : Integer; - end record; -end DSSO1; -@end example - -In this example record types with names starting with `L' have @cite{Low_Order_First} scalar -storage order, and record types with names starting with `H' have @code{High_Order_First}. -Note that in the case of @code{H4a}, the order is not inherited -from the parent type. Only an explicitly set @code{Scalar_Storage_Order} -gets inherited on type derivation. - -If this pragma is used as a configuration pragma which appears within a -configuration pragma file (as opposed to appearing explicitly at the start -of a single unit), then the binder will require that all units in a partition -be compiled in a similar manner, other than run-time units, which are not -affected by this pragma. Note that the use of this form is discouraged because -it may significantly degrade the run-time performance of the software, instead -the default scalar storage order ought to be changed only on a local basis. - -@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{52} -@section Pragma Default_Storage_Pool - - -@geindex Default_Storage_Pool - -Syntax: - -@example -pragma Default_Storage_Pool (storage_pool_NAME | null); -@end example - -This pragma is standard in Ada 2012, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{53}@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{54} -@section Pragma Depends - - -Syntax: - -@example -pragma Depends (DEPENDENCY_RELATION); - -DEPENDENCY_RELATION ::= - null - | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) - -DEPENDENCY_CLAUSE ::= - OUTPUT_LIST =>[+] INPUT_LIST - | NULL_DEPENDENCY_CLAUSE - -NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST - -OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) - -INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) - -OUTPUT ::= NAME | FUNCTION_RESULT -INPUT ::= NAME - -where FUNCTION_RESULT is a function Result attribute_reference -@end example - -For the semantics of this pragma, see the entry for aspect @code{Depends} in the -SPARK 2014 Reference Manual, section 6.1.5. - -@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{55} -@section Pragma Detect_Blocking - - -Syntax: - -@example -pragma Detect_Blocking; -@end example - -This is a standard pragma in Ada 2005, that is available in all earlier -versions of Ada as an implementation-defined pragma. - -This is a configuration pragma that forces the detection of potentially -blocking operations within a protected operation, and to raise Program_Error -if that happens. - -@node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{56} -@section Pragma Disable_Atomic_Synchronization - - -@geindex Atomic Synchronization - -Syntax: - -@example -pragma Disable_Atomic_Synchronization [(Entity)]; -@end example - -Ada requires that accesses (reads or writes) of an atomic variable be -regarded as synchronization points in the case of multiple tasks. -Particularly in the case of multi-processors this may require special -handling, e.g. the generation of memory barriers. This capability may -be turned off using this pragma in cases where it is known not to be -required. - -The placement and scope rules for this pragma are the same as those -for @code{pragma Suppress}. In particular it can be used as a -configuration pragma, or in a declaration sequence where it applies -till the end of the scope. If an @code{Entity} argument is present, -the action applies only to that entity. - -@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{57} -@section Pragma Dispatching_Domain - - -Syntax: - -@example -pragma Dispatching_Domain (EXPRESSION); -@end example - -This pragma is standard in Ada 2012, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{58}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{59} -@section Pragma Effective_Reads - - -Syntax: - -@example -pragma Effective_Reads [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in -the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5a}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5b} -@section Pragma Effective_Writes - - -Syntax: - -@example -pragma Effective_Writes [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Effective_Writes} -in the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5c} -@section Pragma Elaboration_Checks - - -@geindex Elaboration control - -Syntax: - -@example -pragma Elaboration_Checks (Dynamic | Static); -@end example - -This is a configuration pragma which specifies the elaboration model to be -used during compilation. For more information on the elaboration models of -GNAT, consult the chapter on elaboration order handling in the `GNAT User’s -Guide'. - -The pragma may appear in the following contexts: - - -@itemize * - -@item -Configuration pragmas file - -@item -Prior to the context clauses of a compilation unit’s initial declaration -@end itemize - -Any other placement of the pragma will result in a warning and the effects of -the offending pragma will be ignored. - -If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in -effect. If the pragma argument is @code{Static}, then the static elaboration model -is in effect. - -@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5d} -@section Pragma Eliminate - - -@geindex Elimination of unused subprograms - -Syntax: - -@example -pragma Eliminate ( - [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , - [ Entity => ] IDENTIFIER | - SELECTED_COMPONENT | - STRING_LITERAL - [, Source_Location => SOURCE_TRACE ] ); - - SOURCE_TRACE ::= STRING_LITERAL -@end example - -This pragma indicates that the given entity is not used in the program to be -compiled and built, thus allowing the compiler to -eliminate the code or data associated with the named entity. Any reference to -an eliminated entity causes a compile-time or link-time error. - -The pragma has the following semantics, where @code{U} is the unit specified by -the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity} -argument: - - -@itemize * - -@item -@code{E} must be a subprogram that is explicitly declared either: - - -@itemize * - -@item -Within @code{U}, or - -@item -Within a generic package that is instantiated in @code{U}, or - -@item -As an instance of generic subprogram instantiated in @code{U}. -@end itemize - -Otherwise the pragma is ignored. - -@item -If @code{E} is overloaded within @code{U} then, in the absence of a -@code{Source_Location} argument, all overloadings are eliminated. - -@item -If @code{E} is overloaded within @code{U} and only some overloadings -are to be eliminated, then each overloading to be eliminated -must be specified in a corresponding pragma @code{Eliminate} -with a @code{Source_Location} argument identifying the line where the -declaration appears, as described below. - -@item -If @code{E} is declared as the result of a generic instantiation, then -a @code{Source_Location} argument is needed, as described below. -@end itemize - -Pragma @code{Eliminate} allows a program to be compiled in a system-independent -manner, so that unused entities are eliminated but without -needing to modify the source text. Normally the required set of -@code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool. - -Any source file change that removes, splits, or -adds lines may make the set of @code{Eliminate} pragmas invalid because their -@code{Source_Location} argument values may get out of date. - -Pragma @code{Eliminate} may be used where the referenced entity is a dispatching -operation. In this case all the subprograms to which the given operation can -dispatch are considered to be unused (are never called as a result of a direct -or a dispatching call). - -The string literal given for the source location specifies the line number -of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}: - -@example -SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] - -LBRACKET ::= '[' -RBRACKET ::= ']' - -SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER - -LINE_NUMBER ::= DIGIT @{DIGIT@} -@end example - -Spaces around the colon in a @code{SOURCE_REFERENCE} are optional. - -The source trace that is given as the @code{Source_Location} must obey the -following rules (or else the pragma is ignored), where @code{U} is -the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the -subprogram specified by the @code{Entity} argument: - - -@itemize * - -@item -@code{FILE_NAME} is the short name (with no directory -information) of the Ada source file for @code{U}, using the required syntax -for the underlying file system (e.g. case is significant if the underlying -operating system is case sensitive). -If @code{U} is a package and @code{E} is a subprogram declared in the package -specification and its full declaration appears in the package body, -then the relevant source file is the one for the package specification; -analogously if @code{U} is a generic package. - -@item -If @code{E} is not declared in a generic instantiation (this includes -generic subprogram instances), the source trace includes only one source -line reference. @code{LINE_NUMBER} gives the line number of the occurrence -of the declaration of @code{E} within the source file (as a decimal literal -without an exponent or point). - -@item -If @code{E} is declared by a generic instantiation, its source trace -(from left to right) starts with the source location of the -declaration of @code{E} in the generic unit and ends with the source -location of the instantiation, given in square brackets. This approach is -applied recursively with nested instantiations: the rightmost (nested -most deeply in square brackets) element of the source trace is the location -of the outermost instantiation, and the leftmost element (that is, outside -of any square brackets) is the location of the declaration of @code{E} in -the generic unit. -@end itemize - -Examples: - -@quotation - -@example -pragma Eliminate (Pkg0, Proc); --- Eliminate (all overloadings of) Proc in Pkg0 - -pragma Eliminate (Pkg1, Proc, - Source_Location => "pkg1.ads:8"); --- Eliminate overloading of Proc at line 8 in pkg1.ads - --- Assume the following file contents: --- gen_pkg.ads --- 1: generic --- 2: type T is private; --- 3: package Gen_Pkg is --- 4: procedure Proc(N : T); --- ... ... --- ... end Gen_Pkg; --- --- q.adb --- 1: with Gen_Pkg; --- 2: procedure Q is --- 3: package Inst_Pkg is new Gen_Pkg(Integer); --- ... -- No calls on Inst_Pkg.Proc --- ... end Q; - --- The following pragma eliminates Inst_Pkg.Proc from Q -pragma Eliminate (Q, Proc, - Source_Location => "gen_pkg.ads:4[q.adb:3]"); -@end example -@end quotation - -@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5e} -@section Pragma Enable_Atomic_Synchronization - - -@geindex Atomic Synchronization - -Syntax: - -@example -pragma Enable_Atomic_Synchronization [(Entity)]; -@end example - -Ada requires that accesses (reads or writes) of an atomic variable be -regarded as synchronization points in the case of multiple tasks. -Particularly in the case of multi-processors this may require special -handling, e.g. the generation of memory barriers. This synchronization -is performed by default, but can be turned off using -@code{pragma Disable_Atomic_Synchronization}. The -@code{Enable_Atomic_Synchronization} pragma can be used to turn -it back on. - -The placement and scope rules for this pragma are the same as those -for @code{pragma Unsuppress}. In particular it can be used as a -configuration pragma, or in a declaration sequence where it applies -till the end of the scope. If an @code{Entity} argument is present, -the action applies only to that entity. - -@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{5f} -@section Pragma Export_Function - - -@geindex Argument passing mechanisms - -Syntax: - -@example -pragma Export_Function ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Result_Type =>] result_SUBTYPE_MARK] - [, [Mechanism =>] MECHANISM] - [, [Result_Mechanism =>] MECHANISM_NAME]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -| "" - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= Value | Reference -@end example - -Use this pragma to make a function externally callable and optionally -provide information on mechanisms to be used for passing parameter and -result values. We recommend, for the purposes of improving portability, -this pragma always be used in conjunction with a separate pragma -@code{Export}, which must precede the pragma @code{Export_Function}. -GNAT does not require a separate pragma @code{Export}, but if none is -present, @code{Convention Ada} is assumed, which is usually -not what is wanted, so it is usually appropriate to use this -pragma in conjunction with a @code{Export} or @code{Convention} -pragma that specifies the desired foreign convention. -Pragma @code{Export_Function} -(and @code{Export}, if present) must appear in the same declarative -region as the function to which they apply. - -The @code{internal_name} must uniquely designate the function to which the -pragma applies. If more than one function name exists of this name in -the declarative part you must use the @code{Parameter_Types} and -@code{Result_Type} parameters to achieve the required -unique designation. The @cite{subtype_mark}s in these parameters must -exactly match the subtypes in the corresponding function specification, -using positional notation to match parameters with subtype marks. -The form with an @code{'Access} attribute can be used to match an -anonymous access parameter. - -@geindex Suppressing external name - -Special treatment is given if the EXTERNAL is an explicit null -string or a static string expressions that evaluates to the null -string. In this case, no external name is generated. This form -still allows the specification of parameter mechanisms. - -@node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{60} -@section Pragma Export_Object - - -Syntax: - -@example -pragma Export_Object ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -@end example - -This pragma designates an object as exported, and apart from the -extended rules for external symbols, is identical in effect to the use of -the normal @code{Export} pragma applied to an object. You may use a -separate Export pragma (and you probably should from the point of view -of portability), but it is not required. @code{Size} is syntax checked, -but otherwise ignored by GNAT. - -@node Pragma Export_Procedure,Pragma Export_Valued_Procedure,Pragma Export_Object,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{61} -@section Pragma Export_Procedure - - -Syntax: - -@example -pragma Export_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -| "" - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= Value | Reference -@end example - -This pragma is identical to @code{Export_Function} except that it -applies to a procedure rather than a function and the parameters -@code{Result_Type} and @code{Result_Mechanism} are not permitted. -GNAT does not require a separate pragma @code{Export}, but if none is -present, @code{Convention Ada} is assumed, which is usually -not what is wanted, so it is usually appropriate to use this -pragma in conjunction with a @code{Export} or @code{Convention} -pragma that specifies the desired foreign convention. - -@geindex Suppressing external name - -Special treatment is given if the EXTERNAL is an explicit null -string or a static string expressions that evaluates to the null -string. In this case, no external name is generated. This form -still allows the specification of parameter mechanisms. - -@node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Procedure,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{62} -@section Pragma Export_Valued_Procedure - - -Syntax: - -@example -pragma Export_Valued_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -| "" - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= Value | Reference -@end example - -This pragma is identical to @code{Export_Procedure} except that the -first parameter of @code{LOCAL_NAME}, which must be present, must be of -mode @code{out}, and externally the subprogram is treated as a function -with this parameter as the result of the function. GNAT provides for -this capability to allow the use of @code{out} and @code{in out} -parameters in interfacing to external functions (which are not permitted -in Ada functions). -GNAT does not require a separate pragma @code{Export}, but if none is -present, @code{Convention Ada} is assumed, which is almost certainly -not what is wanted since the whole point of this pragma is to interface -with foreign language functions, so it is usually appropriate to use this -pragma in conjunction with a @code{Export} or @code{Convention} -pragma that specifies the desired foreign convention. - -@geindex Suppressing external name - -Special treatment is given if the EXTERNAL is an explicit null -string or a static string expressions that evaluates to the null -string. In this case, no external name is generated. This form -still allows the specification of parameter mechanisms. - -@node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{63} -@section Pragma Extend_System - - -@geindex System -@geindex extending - -@geindex DEC Ada 83 - -Syntax: - -@example -pragma Extend_System ([Name =>] IDENTIFIER); -@end example - -This pragma is used to provide backwards compatibility with other -implementations that extend the facilities of package @code{System}. In -GNAT, @code{System} contains only the definitions that are present in -the Ada RM. However, other implementations, notably the DEC Ada 83 -implementation, provide many extensions to package @code{System}. - -For each such implementation accommodated by this pragma, GNAT provides a -package @code{Aux_@var{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83 -implementation, which provides the required additional definitions. You -can use this package in two ways. You can @code{with} it in the normal -way and access entities either by selection or using a @code{use} -clause. In this case no special processing is required. - -However, if existing code contains references such as -@code{System.@var{xxx}} where `xxx' is an entity in the extended -definitions provided in package @code{System}, you may use this pragma -to extend visibility in @code{System} in a non-standard way that -provides greater compatibility with the existing code. Pragma -@code{Extend_System} is a configuration pragma whose single argument is -the name of the package containing the extended definition -(e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under -control of this pragma will be processed using special visibility -processing that looks in package @code{System.Aux_@var{xxx}} where -@code{Aux_@var{xxx}} is the pragma argument for any entity referenced in -package @code{System}, but not found in package @code{System}. - -You can use this pragma either to access a predefined @code{System} -extension supplied with the compiler, for example @code{Aux_DEC} or -you can construct your own extension unit following the above -definition. Note that such a package is a child of @code{System} -and thus is considered part of the implementation. -To compile it you will have to use the `-gnatg' switch -for compiling System units, as explained in the -GNAT User’s Guide. - -@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{64} -@section Pragma Extensions_Allowed - - -@geindex Ada Extensions - -@geindex GNAT Extensions - -Syntax: - -@example -pragma Extensions_Allowed (On | Off | All); -@end example - -This configuration pragma enables (via the “On” or “All” argument) or disables -(via the “Off” argument) the implementation extension mode; the pragma takes -precedence over the `-gnatX' and `-gnatX0' command switches. - -If an argument of “All” is specified, the latest version of the Ada language -is implemented (currently Ada 2022) and, in addition, a number -of GNAT specific extensions are recognized. These extensions are listed -below. An argument of “On” has the same effect except that only -some, not all, of the listed extensions are enabled; those extensions -are identified below. - - -@itemize * - -@item -Constrained attribute for generic objects - -The @code{Constrained} attribute is permitted for objects of -generic types. The result indicates if the corresponding actual -is constrained. - -@item -@code{Static} aspect on intrinsic functions - -The Ada 202x @code{Static} aspect can be specified on Intrinsic imported -functions and the compiler will evaluate some of these intrinsic statically, -in particular the @code{Shift_Left} and @code{Shift_Right} intrinsics. - -An Extensions_Allowed pragma argument of “On” enables this extension. - -@item -@code{[]} aggregates - -This new aggregate syntax for arrays and containers is provided under -gnatX -to experiment and confirm this new language syntax. - -@item -Additional @code{when} constructs - -In addition to the @code{exit when CONDITION} control structure, several -additional constructs are allowed following this format. Including -@code{return when CONDITION}, @code{goto when CONDITION}, and -@code{raise [with EXCEPTION_MESSAGE] when CONDITION.} - -Some examples: - -@example -return Result when Variable > 10; - -raise Program_Error with "Element is null" when Element = null; - -goto End_Of_Subprogram when Variable = -1; -@end example - -@item -Casing on composite values (aka pattern matching) - -The selector for a case statement may be of a composite type, subject to -some restrictions (described below). Aggregate syntax is used for choices -of such a case statement; however, in cases where a “normal” aggregate would -require a discrete value, a discrete subtype may be used instead; box -notation can also be used to match all values. - -Consider this example: - -@example -type Rec is record - F1, F2 : Integer; -end record; - -procedure Caser_1 (X : Rec) is -begin - case X is - when (F1 => Positive, F2 => Positive) => - Do_This; - when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) => - Do_That; - when others => - Do_The_Other_Thing; - end case; -end Caser_1; -@end example - -If Caser_1 is called and both components of X are positive, then -Do_This will be called; otherwise, if either component is nonnegative -then Do_That will be called; otherwise, Do_The_Other_Thing will be called. - -If the set of values that match the choice(s) of an earlier alternative -overlaps the corresponding set of a later alternative, then the first -set shall be a proper subset of the second (and the later alternative -will not be executed if the earlier alternative “matches”). All possible -values of the composite type shall be covered. The composite type of the -selector shall be an array or record type that is neither limited -class-wide. Currently, a “when others =>” case choice is required; it is -intended that this requirement will be relaxed at some point. - -If a subcomponent’s subtype does not meet certain restrictions, then -the only value that can be specified for that subcomponent in a case -choice expression is a “box” component association (which matches all -possible values for the subcomponent). This restriction applies if - - -@itemize - - -@item -the component subtype is not a record, array, or discrete type; or - -@item -the component subtype is subject to a non-static constraint or -has a predicate; or - -@item -the component type is an enumeration type that is subject to an -enumeration representation clause; or - -@item -the component type is a multidimensional array type or an -array type with a nonstatic index subtype. -@end itemize - -Support for casing on arrays (and on records that contain arrays) is -currently subject to some restrictions. Non-positional -array aggregates are not supported as (or within) case choices. Likewise -for array type and subtype names. The current implementation exceeds -compile-time capacity limits in some annoyingly common scenarios; the -message generated in such cases is usually “Capacity exceeded in compiling -case statement with composite selector type”. - -In addition, pattern bindings are supported. This is a mechanism -for binding a name to a component of a matching value for use within -an alternative of a case statement. For a component association -that occurs within a case choice, the expression may be followed by -“is ”. In the special case of a “box” component association, -the identifier may instead be provided within the box. Either of these -indicates that the given identifer denotes (a constant view of) the matching -subcomponent of the case selector. Binding is not yet supported for arrays -or subcomponents thereof. - -Consider this example (which uses type Rec from the previous example): - -@example -procedure Caser_2 (X : Rec) is -begin - case X is - when (F1 => Positive is Abc, F2 => Positive) => - Do_This (Abc) - when (F1 => Natural is N1, F2 => ) | - (F1 => , F2 => Natural is N1) => - Do_That (Param_1 => N1, Param_2 => N2); - when others => - Do_The_Other_Thing; - end case; -end Caser_2; -@end example - -This example is the same as the previous one with respect to -determining whether Do_This, Do_That, or Do_The_Other_Thing will -be called. But for this version, Do_This takes a parameter and Do_That -takes two parameters. If Do_This is called, the actual parameter in the -call will be X.F1. - -If Do_That is called, the situation is more complex because there are two -choices for that alternative. If Do_That is called because the first choice -matched (i.e., because X.F1 is nonnegative and either X.F1 or X.F2 is zero -or negative), then the actual parameters of the call will be (in order) -X.F1 and X.F2. If Do_That is called because the second choice matched (and -the first one did not), then the actual parameters will be reversed. - -Within the choice list for single alternative, each choice must -define the same set of bindings and the component subtypes for -for a given identifer must all statically match. Currently, the case -of a binding for a nondiscrete component is not implemented. - -An Extensions_Allowed pragma argument of “On” enables this extension. - -@item -Fixed lower bounds for array types and subtypes - -Unconstrained array types and subtypes can be specified with a lower bound -that is fixed to a certain value, by writing an index range that uses the -syntax “ .. <>”. This guarantees that all objects -of the type or subtype will have the specified lower bound. - -For example, a matrix type with fixed lower bounds of zero for each -dimension can be declared by the following: - -@example -type Matrix is - array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer; -@end example - -Objects of type Matrix declared with an index constraint must have index -ranges starting at zero: - -@example -M1 : Matrix (0 .. 9, 0 .. 19); -M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE -@end example - -Similarly, a subtype of String can be declared that specifies the lower -bound of objects of that subtype to be 1: - -@quotation - -@example -subtype String_1 is String (1 .. <>); -@end example -@end quotation - -If a string slice is passed to a formal of subtype String_1 in a call to -a subprogram S, the slice’s bounds will “slide” so that the lower bound -is 1. Within S, the lower bound of the formal is known to be 1, so, unlike -a normal unconstrained String formal, there is no need to worry about -accounting for other possible lower-bound values. Sliding of bounds also -occurs in other contexts, such as for object declarations with an -unconstrained subtype with fixed lower bound, as well as in subtype -conversions. - -Use of this feature increases safety by simplifying code, and can also -improve the efficiency of indexing operations, since the compiler statically -knows the lower bound of unconstrained array formals when the formal’s -subtype has index ranges with static fixed lower bounds. - -An Extensions_Allowed pragma argument of “On” enables this extension. - -@item -Prefixed-view notation for calls to primitive subprograms of untagged types - -Since Ada 2005, calls to primitive subprograms of a tagged type that -have a “prefixed view” (see RM 4.1.3(9.2)) have been allowed to be -written using the form of a selected_component, with the first actual -parameter given as the prefix and the name of the subprogram as a -selector. This prefixed-view notation for calls is extended so as to -also allow such syntax for calls to primitive subprograms of untagged -types. The primitives of an untagged type T that have a prefixed view -are those where the first formal parameter of the subprogram either -is of type T or is an anonymous access parameter whose designated type -is T. For a type that has a component that happens to have the same -simple name as one of the type’s primitive subprograms, where the -component is visible at the point of a selected_component using that -name, preference is given to the component in a selected_component -(as is currently the case for tagged types with such component names). - -An Extensions_Allowed pragma argument of “On” enables this extension. - -@item -Expression defaults for generic formal functions - -The declaration of a generic formal function is allowed to specify -an expression as a default, using the syntax of an expression function. - -Here is an example of this feature: - -@example -generic - type T is private; - with function Copy (Item : T) return T is (Item); -- Defaults to Item -package Stacks is - - type Stack is limited private; - - procedure Push (S : in out Stack; X : T); -- Calls Copy on X - - function Pop (S : in out Stack) return T; -- Calls Copy to return item - -private - -- ... -end Stacks; -@end example -@end itemize - -@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{65}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{66} -@section Pragma Extensions_Visible - - -Syntax: - -@example -pragma Extensions_Visible [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} -in the SPARK 2014 Reference Manual, section 6.1.7. - -@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{67} -@section Pragma External - - -Syntax: - -@example -pragma External ( - [ Convention =>] convention_IDENTIFIER, - [ Entity =>] LOCAL_NAME - [, [External_Name =>] static_string_EXPRESSION ] - [, [Link_Name =>] static_string_EXPRESSION ]); -@end example - -This pragma is identical in syntax and semantics to pragma -@code{Export} as defined in the Ada Reference Manual. It is -provided for compatibility with some Ada 83 compilers that -used this pragma for exactly the same purposes as pragma -@code{Export} before the latter was standardized. - -@node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{68} -@section Pragma External_Name_Casing - - -@geindex Dec Ada 83 casing compatibility - -@geindex External Names -@geindex casing - -@geindex Casing of External names - -Syntax: - -@example -pragma External_Name_Casing ( - Uppercase | Lowercase - [, Uppercase | Lowercase | As_Is]); -@end example - -This pragma provides control over the casing of external names associated -with Import and Export pragmas. There are two cases to consider: - - -@itemize * - -@item -Implicit external names - -Implicit external names are derived from identifiers. The most common case -arises when a standard Ada Import or Export pragma is used with only two -arguments, as in: - -@example -pragma Import (C, C_Routine); -@end example - -Since Ada is a case-insensitive language, the spelling of the identifier in -the Ada source program does not provide any information on the desired -casing of the external name, and so a convention is needed. In GNAT the -default treatment is that such names are converted to all lower case -letters. This corresponds to the normal C style in many environments. -The first argument of pragma @code{External_Name_Casing} can be used to -control this treatment. If @code{Uppercase} is specified, then the name -will be forced to all uppercase letters. If @code{Lowercase} is specified, -then the normal default of all lower case letters will be used. - -This same implicit treatment is also used in the case of extended DEC Ada 83 -compatible Import and Export pragmas where an external name is explicitly -specified using an identifier rather than a string. - -@item -Explicit external names - -Explicit external names are given as string literals. The most common case -arises when a standard Ada Import or Export pragma is used with three -arguments, as in: - -@example -pragma Import (C, C_Routine, "C_routine"); -@end example - -In this case, the string literal normally provides the exact casing required -for the external name. The second argument of pragma -@code{External_Name_Casing} may be used to modify this behavior. -If @code{Uppercase} is specified, then the name -will be forced to all uppercase letters. If @code{Lowercase} is specified, -then the name will be forced to all lowercase letters. A specification of -@code{As_Is} provides the normal default behavior in which the casing is -taken from the string provided. -@end itemize - -This pragma may appear anywhere that a pragma is valid. In particular, it -can be used as a configuration pragma in the @code{gnat.adc} file, in which -case it applies to all subsequent compilations, or it can be used as a program -unit pragma, in which case it only applies to the current unit, or it can -be used more locally to control individual Import/Export pragmas. - -It was primarily intended for use with OpenVMS systems, where many -compilers convert all symbols to upper case by default. For interfacing to -such compilers (e.g., the DEC C compiler), it may be convenient to use -the pragma: - -@example -pragma External_Name_Casing (Uppercase, Uppercase); -@end example - -to enforce the upper casing of all external symbols. - -@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{69} -@section Pragma Fast_Math - - -Syntax: - -@example -pragma Fast_Math; -@end example - -This is a configuration pragma which activates a mode in which speed is -considered more important for floating-point operations than absolutely -accurate adherence to the requirements of the standard. Currently the -following operations are affected: - - -@table @asis - -@item `Complex Multiplication' - -The normal simple formula for complex multiplication can result in intermediate -overflows for numbers near the end of the range. The Ada standard requires that -this situation be detected and corrected by scaling, but in Fast_Math mode such -cases will simply result in overflow. Note that to take advantage of this you -must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} -under control of the pragma, rather than use the preinstantiated versions. -@end table - -@node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6a}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6b} -@section Pragma Favor_Top_Level - - -Syntax: - -@example -pragma Favor_Top_Level (type_NAME); -@end example - -The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram -type. This pragma is an efficiency hint to the compiler, regarding the use of -@code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. -The pragma means that nested subprograms are not used with this type, or are -rare, so that the generated code should be efficient in the top-level case. -When this pragma is used, dynamically generated trampolines may be used on some -targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. - -@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6c} -@section Pragma Finalize_Storage_Only - - -Syntax: - -@example -pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); -@end example - -The argument of pragma @code{Finalize_Storage_Only} must denote a local type which -is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The -pragma suppresses the call to @code{Finalize} for declared library-level objects -of the argument type. This is mostly useful for types where finalization is -only used to deal with storage reclamation since in most environments it is -not necessary to reclaim memory just before terminating execution, hence the -name. Note that this pragma does not suppress Finalize calls for library-level -heap-allocated objects (see pragma @code{No_Heap_Finalization}). - -@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{6d} -@section Pragma Float_Representation - - -Syntax: - -@example -pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); - -FLOAT_REP ::= VAX_Float | IEEE_Float -@end example - -In the one argument form, this pragma is a configuration pragma which -allows control over the internal representation chosen for the predefined -floating point types declared in the packages @code{Standard} and -@code{System}. This pragma is only provided for compatibility and has no effect. - -The two argument form specifies the representation to be used for -the specified floating-point type. The argument must -be @code{IEEE_Float} to specify the use of IEEE format, as follows: - - -@itemize * - -@item -For a digits value of 6, 32-bit IEEE short format will be used. - -@item -For a digits value of 15, 64-bit IEEE long format will be used. - -@item -No other value of digits is permitted. -@end itemize - -@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6e}@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{6f} -@section Pragma Ghost - - -Syntax: - -@example -pragma Ghost [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK -2014 Reference Manual, section 6.9. - -@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{70}@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{71} -@section Pragma Global - - -Syntax: - -@example -pragma Global (GLOBAL_SPECIFICATION); - -GLOBAL_SPECIFICATION ::= - null - | (GLOBAL_LIST) - | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) - -MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST - -MODE_SELECTOR ::= In_Out | Input | Output | Proof_In -GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) -GLOBAL_ITEM ::= NAME -@end example - -For the semantics of this pragma, see the entry for aspect @code{Global} in the -SPARK 2014 Reference Manual, section 6.1.4. - -@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{72} -@section Pragma Ident - - -Syntax: - -@example -pragma Ident (static_string_EXPRESSION); -@end example - -This pragma is identical in effect to pragma @code{Comment}. It is provided -for compatibility with other Ada compilers providing this pragma. - -@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{73} -@section Pragma Ignore_Pragma - - -Syntax: - -@example -pragma Ignore_Pragma (pragma_IDENTIFIER); -@end example - -This is a configuration pragma -that takes a single argument that is a simple identifier. Any subsequent -use of a pragma whose pragma identifier matches this argument will be -silently ignored. This may be useful when legacy code or code intended -for compilation with some other compiler contains pragmas that match the -name, but not the exact implementation, of a GNAT pragma. The use of this -pragma allows such pragmas to be ignored, which may be useful in CodePeer -mode, or during porting of legacy code. - -@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{74} -@section Pragma Implementation_Defined - - -Syntax: - -@example -pragma Implementation_Defined (local_NAME); -@end example - -This pragma marks a previously declared entity as implementation-defined. -For an overloaded entity, applies to the most recent homonym. - -@example -pragma Implementation_Defined; -@end example - -The form with no arguments appears anywhere within a scope, most -typically a package spec, and indicates that all entities that are -defined within the package spec are Implementation_Defined. - -This pragma is used within the GNAT runtime library to identify -implementation-defined entities introduced in language-defined units, -for the purpose of implementing the No_Implementation_Identifiers -restriction. - -@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{75} -@section Pragma Implemented - - -Syntax: - -@example -pragma Implemented (procedure_LOCAL_NAME, implementation_kind); - -implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any -@end example - -This is an Ada 2012 representation pragma which applies to protected, task -and synchronized interface primitives. The use of pragma Implemented provides -a way to impose a static requirement on the overriding operation by adhering -to one of the three implementation kinds: entry, protected procedure or any of -the above. This pragma is available in all earlier versions of Ada as an -implementation-defined pragma. - -@example -type Synch_Iface is synchronized interface; -procedure Prim_Op (Obj : in out Iface) is abstract; -pragma Implemented (Prim_Op, By_Protected_Procedure); - -protected type Prot_1 is new Synch_Iface with - procedure Prim_Op; -- Legal -end Prot_1; - -protected type Prot_2 is new Synch_Iface with - entry Prim_Op; -- Illegal -end Prot_2; - -task type Task_Typ is new Synch_Iface with - entry Prim_Op; -- Illegal -end Task_Typ; -@end example - -When applied to the procedure_or_entry_NAME of a requeue statement, pragma -Implemented determines the runtime behavior of the requeue. Implementation kind -By_Entry guarantees that the action of requeueing will proceed from an entry to -another entry. Implementation kind By_Protected_Procedure transforms the -requeue into a dispatching call, thus eliminating the chance of blocking. Kind -By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on -the target’s overriding subprogram kind. - -@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{76} -@section Pragma Implicit_Packing - - -@geindex Rational Profile - -Syntax: - -@example -pragma Implicit_Packing; -@end example - -This is a configuration pragma that requests implicit packing for packed -arrays for which a size clause is given but no explicit pragma Pack or -specification of Component_Size is present. It also applies to records -where no record representation clause is present. Consider this example: - -@example -type R is array (0 .. 7) of Boolean; -for R'Size use 8; -@end example - -In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause -does not change the layout of a composite object. So the Size clause in the -above example is normally rejected, since the default layout of the array uses -8-bit components, and thus the array requires a minimum of 64 bits. - -If this declaration is compiled in a region of code covered by an occurrence -of the configuration pragma Implicit_Packing, then the Size clause in this -and similar examples will cause implicit packing and thus be accepted. For -this implicit packing to occur, the type in question must be an array of small -components whose size is known at compile time, and the Size clause must -specify the exact size that corresponds to the number of elements in the array -multiplied by the size in bits of the component type (both single and -multi-dimensioned arrays can be controlled with this pragma). - -@geindex Array packing - -Similarly, the following example shows the use in the record case - -@example -type r is record - a, b, c, d, e, f, g, h : boolean; - chr : character; -end record; -for r'size use 16; -@end example - -Without a pragma Pack, each Boolean field requires 8 bits, so the -minimum size is 72 bits, but with a pragma Pack, 16 bits would be -sufficient. The use of pragma Implicit_Packing allows this record -declaration to compile without an explicit pragma Pack. - -@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{77} -@section Pragma Import_Function - - -Syntax: - -@example -pragma Import_Function ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Result_Type =>] SUBTYPE_MARK] - [, [Mechanism =>] MECHANISM] - [, [Result_Mechanism =>] MECHANISM_NAME]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= - Value -| Reference -@end example - -This pragma is used in conjunction with a pragma @code{Import} to -specify additional information for an imported function. The pragma -@code{Import} (or equivalent pragma @code{Interface}) must precede the -@code{Import_Function} pragma and both must appear in the same -declarative part as the function specification. - -The @code{Internal} argument must uniquely designate -the function to which the -pragma applies. If more than one function name exists of this name in -the declarative part you must use the @code{Parameter_Types} and -@code{Result_Type} parameters to achieve the required unique -designation. Subtype marks in these parameters must exactly match the -subtypes in the corresponding function specification, using positional -notation to match parameters with subtype marks. -The form with an @code{'Access} attribute can be used to match an -anonymous access parameter. - -You may optionally use the @code{Mechanism} and @code{Result_Mechanism} -parameters to specify passing mechanisms for the -parameters and result. If you specify a single mechanism name, it -applies to all parameters. Otherwise you may specify a mechanism on a -parameter by parameter basis using either positional or named -notation. If the mechanism is not specified, the default mechanism -is used. - -@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{78} -@section Pragma Import_Object - - -Syntax: - -@example -pragma Import_Object ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -@end example - -This pragma designates an object as imported, and apart from the -extended rules for external symbols, is identical in effect to the use of -the normal @code{Import} pragma applied to an object. Unlike the -subprogram case, you need not use a separate @code{Import} pragma, -although you may do so (and probably should do so from a portability -point of view). @code{size} is syntax checked, but otherwise ignored by -GNAT. - -@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{79} -@section Pragma Import_Procedure - - -Syntax: - -@example -pragma Import_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= Value | Reference -@end example - -This pragma is identical to @code{Import_Function} except that it -applies to a procedure rather than a function and the parameters -@code{Result_Type} and @code{Result_Mechanism} are not permitted. - -@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7a} -@section Pragma Import_Valued_Procedure - - -Syntax: - -@example -pragma Import_Valued_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= Value | Reference -@end example - -This pragma is identical to @code{Import_Procedure} except that the -first parameter of @code{LOCAL_NAME}, which must be present, must be of -mode @code{out}, and externally the subprogram is treated as a function -with this parameter as the result of the function. The purpose of this -capability is to allow the use of @code{out} and @code{in out} -parameters in interfacing to external functions (which are not permitted -in Ada functions). You may optionally use the @code{Mechanism} -parameters to specify passing mechanisms for the parameters. -If you specify a single mechanism name, it applies to all parameters. -Otherwise you may specify a mechanism on a parameter by parameter -basis using either positional or named notation. If the mechanism is not -specified, the default mechanism is used. - -Note that it is important to use this pragma in conjunction with a separate -pragma Import that specifies the desired convention, since otherwise the -default convention is Ada, which is almost certainly not what is required. - -@node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7b} -@section Pragma Independent - - -Syntax: - -@example -pragma Independent (Local_NAME); -@end example - -This pragma is standard in Ada 2012 mode (which also provides an aspect -of the same name). It is also available as an implementation-defined -pragma in all earlier versions. It specifies that the -designated object or all objects of the designated type must be -independently addressable. This means that separate tasks can safely -manipulate such objects. For example, if two components of a record are -independent, then two separate tasks may access these two components. -This may place -constraints on the representation of the object (for instance prohibiting -tight packing). - -@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7c} -@section Pragma Independent_Components - - -Syntax: - -@example -pragma Independent_Components (Local_NAME); -@end example - -This pragma is standard in Ada 2012 mode (which also provides an aspect -of the same name). It is also available as an implementation-defined -pragma in all earlier versions. It specifies that the components of the -designated object, or the components of each object of the designated -type, must be -independently addressable. This means that separate tasks can safely -manipulate separate components in the composite object. This may place -constraints on the representation of the object (for instance prohibiting -tight packing). - -@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{7d}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{7e} -@section Pragma Initial_Condition - - -Syntax: - -@example -pragma Initial_Condition (boolean_EXPRESSION); -@end example - -For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} -in the SPARK 2014 Reference Manual, section 7.1.6. - -@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{7f} -@section Pragma Initialize_Scalars - - -@geindex debugging with Initialize_Scalars - -Syntax: - -@example -pragma Initialize_Scalars - [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ]; - -TYPE_VALUE_PAIR ::= - SCALAR_TYPE => static_EXPRESSION - -SCALAR_TYPE := - Short_Float -| Float -| Long_Float -| Long_Long_Flat -| Signed_8 -| Signed_16 -| Signed_32 -| Signed_64 -| Unsigned_8 -| Unsigned_16 -| Unsigned_32 -| Unsigned_64 -@end example - -This pragma is similar to @code{Normalize_Scalars} conceptually but has two -important differences. - -First, there is no requirement for the pragma to be used uniformly in all units -of a partition. In particular, it is fine to use this just for some or all of -the application units of a partition, without needing to recompile the run-time -library. In the case where some units are compiled with the pragma, and some -without, then a declaration of a variable where the type is defined in package -Standard or is locally declared will always be subject to initialization, as -will any declaration of a scalar variable. For composite variables, whether the -variable is initialized may also depend on whether the package in which the -type of the variable is declared is compiled with the pragma. - -The other important difference is that the programmer can control the value -used for initializing scalar objects. This effect can be achieved in several -different ways: - - -@itemize * - -@item -At compile time, the programmer can specify the invalid value for a -particular family of scalar types using the optional arguments of the pragma. - -The compile-time approach is intended to optimize the generated code for the -pragma, by possibly using fast operations such as @code{memset}. Note that such -optimizations require using values where the bytes all have the same binary -representation. - -@item -At bind time, the programmer has several options: - - -@itemize * - -@item -Initialization with invalid values (similar to Normalize_Scalars, though -for Initialize_Scalars it is not always possible to determine the invalid -values in complex cases like signed component fields with nonstandard -sizes). - -@item -Initialization with high values. - -@item -Initialization with low values. - -@item -Initialization with a specific bit pattern. -@end itemize - -See the GNAT User’s Guide for binder options for specifying these cases. - -The bind-time approach is intended to provide fast turnaround for testing -with different values, without having to recompile the program. - -@item -At execution time, the programmer can specify the invalid values using an -environment variable. See the GNAT User’s Guide for details. - -The execution-time approach is intended to provide fast turnaround for -testing with different values, without having to recompile and rebind the -program. -@end itemize - -Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction -with the enhanced validity checking that is now provided in GNAT, which checks -for invalid values under more conditions. Using this feature (see description -of the `-gnatV' flag in the GNAT User’s Guide) in conjunction with pragma -@code{Initialize_Scalars} provides a powerful new tool to assist in the detection -of problems caused by uninitialized variables. - -Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the -generated code. This may cause your code to be substantially larger. It may -also cause an increase in the amount of stack required, so it is probably a -good idea to turn on stack checking (see description of stack checking in the -GNAT User’s Guide) when using this pragma. - -@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{80}@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{81} -@section Pragma Initializes - - -Syntax: - -@example -pragma Initializes (INITIALIZATION_LIST); - -INITIALIZATION_LIST ::= - null - | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) - -INITIALIZATION_ITEM ::= name [=> INPUT_LIST] - -INPUT_LIST ::= - null - | INPUT - | (INPUT @{, INPUT@}) - -INPUT ::= name -@end example - -For the semantics of this pragma, see the entry for aspect @code{Initializes} in the -SPARK 2014 Reference Manual, section 7.1.5. - -@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{82}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{83} -@section Pragma Inline_Always - - -Syntax: - -@example -pragma Inline_Always (NAME [, NAME]); -@end example - -Similar to pragma @code{Inline} except that inlining is unconditional. -Inline_Always instructs the compiler to inline every direct call to the -subprogram or else to emit a compilation error, independently of any -option, in particular `-gnatn' or `-gnatN' or the optimization level. -It is an error to take the address or access of @code{NAME}. It is also an error to -apply this pragma to a primitive operation of a tagged type. Thanks to such -restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. - -@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{84} -@section Pragma Inline_Generic - - -Syntax: - -@example -pragma Inline_Generic (GNAME @{, GNAME@}); - -GNAME ::= generic_unit_NAME | generic_instance_NAME -@end example - -This pragma is provided for compatibility with Dec Ada 83. It has -no effect in GNAT (which always inlines generics), other -than to check that the given names are all names of generic units or -generic instances. - -@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{85} -@section Pragma Interface - - -Syntax: - -@example -pragma Interface ( - [Convention =>] convention_identifier, - [Entity =>] local_NAME - [, [External_Name =>] static_string_expression] - [, [Link_Name =>] static_string_expression]); -@end example - -This pragma is identical in syntax and semantics to -the standard Ada pragma @code{Import}. It is provided for compatibility -with Ada 83. The definition is upwards compatible both with pragma -@code{Interface} as defined in the Ada 83 Reference Manual, and also -with some extended implementations of this pragma in certain Ada 83 -implementations. The only difference between pragma @code{Interface} -and pragma @code{Import} is that there is special circuitry to allow -both pragmas to appear for the same subprogram entity (normally it -is illegal to have multiple @code{Import} pragmas). This is useful in -maintaining Ada 83/Ada 95 compatibility and is compatible with other -Ada 83 compilers. - -@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{86} -@section Pragma Interface_Name - - -Syntax: - -@example -pragma Interface_Name ( - [Entity =>] LOCAL_NAME - [, [External_Name =>] static_string_EXPRESSION] - [, [Link_Name =>] static_string_EXPRESSION]); -@end example - -This pragma provides an alternative way of specifying the interface name -for an interfaced subprogram, and is provided for compatibility with Ada -83 compilers that use the pragma for this purpose. You must provide at -least one of @code{External_Name} or @code{Link_Name}. - -@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{87} -@section Pragma Interrupt_Handler - - -Syntax: - -@example -pragma Interrupt_Handler (procedure_LOCAL_NAME); -@end example - -This program unit pragma is supported for parameterless protected procedures -as described in Annex C of the Ada Reference Manual. - -@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{88} -@section Pragma Interrupt_State - - -Syntax: - -@example -pragma Interrupt_State - ([Name =>] value, - [State =>] SYSTEM | RUNTIME | USER); -@end example - -Normally certain interrupts are reserved to the implementation. Any attempt -to attach an interrupt causes Program_Error to be raised, as described in -RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in -many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is -reserved to the implementation, so that @code{Ctrl-C} can be used to -interrupt execution. Additionally, signals such as @code{SIGSEGV}, -@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific -Ada exceptions, or used to implement run-time functions such as the -@code{abort} statement and stack overflow checking. - -Pragma @code{Interrupt_State} provides a general mechanism for overriding -such uses of interrupts. It subsumes the functionality of pragma -@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not -available on Windows. On all other platforms than VxWorks, -it applies to signals; on VxWorks, it applies to vectored hardware interrupts -and may be used to mark interrupts required by the board support package -as reserved. - -Interrupts can be in one of three states: - - -@itemize * - -@item -System - -The interrupt is reserved (no Ada handler can be installed), and the -Ada run-time may not install a handler. As a result you are guaranteed -standard system default action if this interrupt is raised. This also allows -installing a low level handler via C APIs such as sigaction(), outside -of Ada control. - -@item -Runtime - -The interrupt is reserved (no Ada handler can be installed). The run time -is allowed to install a handler for internal control purposes, but is -not required to do so. - -@item -User - -The interrupt is unreserved. The user may install an Ada handler via -Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide -some other action. -@end itemize - -These states are the allowed values of the @code{State} parameter of the -pragma. The @code{Name} parameter is a value of the type -@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in -@code{Ada.Interrupts.Names}. - -This is a configuration pragma, and the binder will check that there -are no inconsistencies between different units in a partition in how a -given interrupt is specified. It may appear anywhere a pragma is legal. - -The effect is to move the interrupt to the specified state. - -By declaring interrupts to be SYSTEM, you guarantee the standard system -action, such as a core dump. - -By declaring interrupts to be USER, you guarantee that you can install -a handler. - -Note that certain signals on many operating systems cannot be caught and -handled by applications. In such cases, the pragma is ignored. See the -operating system documentation, or the value of the array @code{Reserved} -declared in the spec of package @code{System.OS_Interface}. - -Overriding the default state of signals used by the Ada runtime may interfere -with an application’s runtime behavior in the cases of the synchronous signals, -and in the case of the signal used to implement the @code{abort} statement. - -@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{89}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8a} -@section Pragma Invariant - - -Syntax: - -@example -pragma Invariant - ([Entity =>] private_type_LOCAL_NAME, - [Check =>] EXPRESSION - [,[Message =>] String_Expression]); -@end example - -This pragma provides exactly the same capabilities as the Type_Invariant aspect -defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The -Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it -requires the use of the aspect syntax, which is not available except in 2012 -mode, it is not possible to use the Type_Invariant aspect in earlier versions -of Ada. However the Invariant pragma may be used in any version of Ada. Also -note that the aspect Invariant is a synonym in GNAT for the aspect -Type_Invariant, but there is no pragma Type_Invariant. - -The pragma must appear within the visible part of the package specification, -after the type to which its Entity argument appears. As with the Invariant -aspect, the Check expression is not analyzed until the end of the visible -part of the package, so it may contain forward references. The Message -argument, if present, provides the exception message used if the invariant -is violated. If no Message parameter is provided, a default message that -identifies the line on which the pragma appears is used. - -It is permissible to have multiple Invariants for the same type entity, in -which case they are and’ed together. It is permissible to use this pragma -in Ada 2012 mode, but you cannot have both an invariant aspect and an -invariant pragma for the same entity. - -For further details on the use of this pragma, see the Ada 2012 documentation -of the Type_Invariant aspect. - -@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8b} -@section Pragma Keep_Names - - -Syntax: - -@example -pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); -@end example - -The @code{LOCAL_NAME} argument -must refer to an enumeration first subtype -in the current declarative part. The effect is to retain the enumeration -literal names for use by @code{Image} and @code{Value} even if a global -@code{Discard_Names} pragma applies. This is useful when you want to -generally suppress enumeration literal names and for example you therefore -use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you -want to retain the names for specific enumeration types. - -@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8c} -@section Pragma License - - -@geindex License checking - -Syntax: - -@example -pragma License (Unrestricted | GPL | Modified_GPL | Restricted); -@end example - -This pragma is provided to allow automated checking for appropriate license -conditions with respect to the standard and modified GPL. A pragma -@code{License}, which is a configuration pragma that typically appears at -the start of a source file or in a separate @code{gnat.adc} file, specifies -the licensing conditions of a unit as follows: - - -@itemize * - -@item -Unrestricted -This is used for a unit that can be freely used with no license restrictions. -Examples of such units are public domain units, and units from the Ada -Reference Manual. - -@item -GPL -This is used for a unit that is licensed under the unmodified GPL, and which -therefore cannot be @code{with}ed by a restricted unit. - -@item -Modified_GPL -This is used for a unit licensed under the GNAT modified GPL that includes -a special exception paragraph that specifically permits the inclusion of -the unit in programs without requiring the entire program to be released -under the GPL. - -@item -Restricted -This is used for a unit that is restricted in that it is not permitted to -depend on units that are licensed under the GPL. Typical examples are -proprietary code that is to be released under more restrictive license -conditions. Note that restricted units are permitted to @code{with} units -which are licensed under the modified GPL (this is the whole point of the -modified GPL). -@end itemize - -Normally a unit with no @code{License} pragma is considered to have an -unknown license, and no checking is done. However, standard GNAT headers -are recognized, and license information is derived from them as follows. - -A GNAT license header starts with a line containing 78 hyphens. The following -comment text is searched for the appearance of any of the following strings. - -If the string ‘GNU General Public License’ is found, then the unit is assumed -to have GPL license, unless the string ‘As a special exception’ follows, in -which case the license is assumed to be modified GPL. - -If one of the strings -‘This specification is adapted from the Ada Semantic Interface’ or -‘This specification is derived from the Ada Reference Manual’ is found -then the unit is assumed to be unrestricted. - -These default actions means that a program with a restricted license pragma -will automatically get warnings if a GPL unit is inappropriately -@code{with}ed. For example, the program: - -@example -with Sem_Ch3; -with GNAT.Sockets; -procedure Secret_Stuff is - ... -end Secret_Stuff -@end example - -if compiled with pragma @code{License} (@code{Restricted}) in a -@code{gnat.adc} file will generate the warning: - -@example -1. with Sem_Ch3; - | - >>> license of withed unit "Sem_Ch3" is incompatible - -2. with GNAT.Sockets; -3. procedure Secret_Stuff is -@end example - -Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT -compiler and is licensed under the -GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT -run time, and is therefore licensed under the modified GPL. - -@node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{8d} -@section Pragma Link_With - - -Syntax: - -@example -pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); -@end example - -This pragma is provided for compatibility with certain Ada 83 compilers. -It has exactly the same effect as pragma @code{Linker_Options} except -that spaces occurring within one of the string expressions are treated -as separators. For example, in the following case: - -@example -pragma Link_With ("-labc -ldef"); -@end example - -results in passing the strings @code{-labc} and @code{-ldef} as two -separate arguments to the linker. In addition pragma Link_With allows -multiple arguments, with the same effect as successive pragmas. - -@node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{8e} -@section Pragma Linker_Alias - - -Syntax: - -@example -pragma Linker_Alias ( - [Entity =>] LOCAL_NAME, - [Target =>] static_string_EXPRESSION); -@end example - -@code{LOCAL_NAME} must refer to an object that is declared at the library -level. This pragma establishes the given entity as a linker alias for the -given target. It is equivalent to @code{__attribute__((alias))} in GNU C -and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol -@code{static_string_EXPRESSION} in the object file, that is to say no space -is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved -to the same address as @code{static_string_EXPRESSION} by the linker. - -The actual linker name for the target must be used (e.g., the fully -encoded name with qualification in Ada, or the mangled name in C++), -or it must be declared using the C convention with @code{pragma Import} -or @code{pragma Export}. - -Not all target machines support this pragma. On some of them it is accepted -only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. - -@example --- Example of the use of pragma Linker_Alias - -package p is - i : Integer := 1; - pragma Export (C, i); - - new_name_for_i : Integer; - pragma Linker_Alias (new_name_for_i, "i"); -end p; -@end example - -@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{8f} -@section Pragma Linker_Constructor - - -Syntax: - -@example -pragma Linker_Constructor (procedure_LOCAL_NAME); -@end example - -@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that -is declared at the library level. A procedure to which this pragma is -applied will be treated as an initialization routine by the linker. -It is equivalent to @code{__attribute__((constructor))} in GNU C and -causes @code{procedure_LOCAL_NAME} to be invoked before the entry point -of the executable is called (or immediately after the shared library is -loaded if the procedure is linked in a shared library), in particular -before the Ada run-time environment is set up. - -Because of these specific contexts, the set of operations such a procedure -can perform is very limited and the type of objects it can manipulate is -essentially restricted to the elementary types. In particular, it must only -contain code to which pragma Restrictions (No_Elaboration_Code) applies. - -This pragma is used by GNAT to implement auto-initialization of shared Stand -Alone Libraries, which provides a related capability without the restrictions -listed above. Where possible, the use of Stand Alone Libraries is preferable -to the use of this pragma. - -@node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{90} -@section Pragma Linker_Destructor - - -Syntax: - -@example -pragma Linker_Destructor (procedure_LOCAL_NAME); -@end example - -@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that -is declared at the library level. A procedure to which this pragma is -applied will be treated as a finalization routine by the linker. -It is equivalent to @code{__attribute__((destructor))} in GNU C and -causes @code{procedure_LOCAL_NAME} to be invoked after the entry point -of the executable has exited (or immediately before the shared library -is unloaded if the procedure is linked in a shared library), in particular -after the Ada run-time environment is shut down. - -See @code{pragma Linker_Constructor} for the set of restrictions that apply -because of these specific contexts. - -@node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{91}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{92} -@section Pragma Linker_Section - - -Syntax: - -@example -pragma Linker_Section ( - [Entity =>] LOCAL_NAME, - [Section =>] static_string_EXPRESSION); -@end example - -@code{LOCAL_NAME} must refer to an object, type, or subprogram that is -declared at the library level. This pragma specifies the name of the -linker section for the given entity. It is equivalent to -@code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to -be placed in the @code{static_string_EXPRESSION} section of the -executable (assuming the linker doesn’t rename the section). -GNAT also provides an implementation defined aspect of the same name. - -In the case of specifying this aspect for a type, the effect is to -specify the corresponding section for all library-level objects of -the type that do not have an explicit linker section set. Note that -this only applies to whole objects, not to components of composite objects. - -In the case of a subprogram, the linker section applies to all previously -declared matching overloaded subprograms in the current declarative part -which do not already have a linker section assigned. The linker section -aspect is useful in this case for specifying different linker sections -for different elements of such an overloaded set. - -Note that an empty string specifies that no linker section is specified. -This is not quite the same as omitting the pragma or aspect, since it -can be used to specify that one element of an overloaded set of subprograms -has the default linker section, or that one object of a type for which a -linker section is specified should has the default linker section. - -The compiler normally places library-level entities in standard sections -depending on the class: procedures and functions generally go in the -@code{.text} section, initialized variables in the @code{.data} section -and uninitialized variables in the @code{.bss} section. - -Other, special sections may exist on given target machines to map special -hardware, for example I/O ports or flash memory. This pragma is a means to -defer the final layout of the executable to the linker, thus fully working -at the symbolic level with the compiler. - -Some file formats do not support arbitrary sections so not all target -machines support this pragma. The use of this pragma may cause a program -execution to be erroneous if it is used to place an entity into an -inappropriate section (e.g., a modified variable into the @code{.text} -section). See also @code{pragma Persistent_BSS}. - -@example --- Example of the use of pragma Linker_Section - -package IO_Card is - Port_A : Integer; - pragma Volatile (Port_A); - pragma Linker_Section (Port_A, ".bss.port_a"); - - Port_B : Integer; - pragma Volatile (Port_B); - pragma Linker_Section (Port_B, ".bss.port_b"); - - type Port_Type is new Integer with Linker_Section => ".bss"; - PA : Port_Type with Linker_Section => ".bss.PA"; - PB : Port_Type; -- ends up in linker section ".bss" - - procedure Q with Linker_Section => "Qsection"; -end IO_Card; -@end example - -@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{93}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{94} -@section Pragma Lock_Free - - -Syntax: -This pragma may be specified for protected types or objects. It specifies that -the implementation of protected operations must be implemented without locks. -Compilation fails if the compiler cannot generate lock-free code for the -operations. - -The current conditions required to support this pragma are: - - -@itemize * - -@item -Protected type declarations may not contain entries - -@item -Protected subprogram declarations may not have nonelementary parameters -@end itemize - -In addition, each protected subprogram body must satisfy: - - -@itemize * - -@item -May reference only one protected component - -@item -May not reference nonconstant entities outside the protected subprogram -scope - -@item -May not contain address representation items, allocators, or quantified -expressions - -@item -May not contain delay, goto, loop, or procedure-call statements - -@item -May not contain exported and imported entities - -@item -May not dereferenced access values - -@item -Function calls and attribute references must be static -@end itemize - -If the Lock_Free aspect is specified to be True for a protected unit -and the Ceiling_Locking locking policy is in effect, then the run-time -actions associated with the Ceiling_Locking locking policy (described in -Ada RM D.3) are not performed when a protected operation of the protected -unit is executed. - -@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{95} -@section Pragma Loop_Invariant - - -Syntax: - -@example -pragma Loop_Invariant ( boolean_EXPRESSION ); -@end example - -The effect of this pragma is similar to that of pragma @code{Assert}, -except that in an @code{Assertion_Policy} pragma, the identifier -@code{Loop_Invariant} is used to control whether it is ignored or checked -(or disabled). - -@code{Loop_Invariant} can only appear as one of the items in the sequence -of statements of a loop body, or nested inside block statements that -appear in the sequence of statements of a loop body. -The intention is that it be used to -represent a “loop invariant” assertion, i.e. something that is true each -time through the loop, and which can be used to show that the loop is -achieving its purpose. - -Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that -apply to the same loop should be grouped in the same sequence of -statements. - -To aid in writing such invariants, the special attribute @code{Loop_Entry} -may be used to refer to the value of an expression on entry to the loop. This -attribute can only be used within the expression of a @code{Loop_Invariant} -pragma. For full details, see documentation of attribute @code{Loop_Entry}. - -@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{96} -@section Pragma Loop_Optimize - - -Syntax: - -@example -pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); - -OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector -@end example - -This pragma must appear immediately within a loop statement. It allows the -programmer to specify optimization hints for the enclosing loop. The hints -are not mutually exclusive and can be freely mixed, but not all combinations -will yield a sensible outcome. - -There are five supported optimization hints for a loop: - - -@itemize * - -@item -Ivdep - -The programmer asserts that there are no loop-carried dependencies -which would prevent consecutive iterations of the loop from being -executed simultaneously. - -@item -No_Unroll - -The loop must not be unrolled. This is a strong hint: the compiler will not -unroll a loop marked with this hint. - -@item -Unroll - -The loop should be unrolled. This is a weak hint: the compiler will try to -apply unrolling to this loop preferably to other optimizations, notably -vectorization, but there is no guarantee that the loop will be unrolled. - -@item -No_Vector - -The loop must not be vectorized. This is a strong hint: the compiler will not -vectorize a loop marked with this hint. - -@item -Vector - -The loop should be vectorized. This is a weak hint: the compiler will try to -apply vectorization to this loop preferably to other optimizations, notably -unrolling, but there is no guarantee that the loop will be vectorized. -@end itemize - -These hints do not remove the need to pass the appropriate switches to the -compiler in order to enable the relevant optimizations, that is to say -`-funroll-loops' for unrolling and `-ftree-vectorize' for -vectorization. - -@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{97} -@section Pragma Loop_Variant - - -Syntax: - -@example -pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); -LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION -CHANGE_DIRECTION ::= Increases | Decreases -@end example - -@code{Loop_Variant} can only appear as one of the items in the sequence -of statements of a loop body, or nested inside block statements that -appear in the sequence of statements of a loop body. -It allows the specification of quantities which must always -decrease or increase in successive iterations of the loop. In its simplest -form, just one expression is specified, whose value must increase or decrease -on each iteration of the loop. - -In a more complex form, multiple arguments can be given which are interpreted -in a nesting lexicographic manner. For example: - -@example -pragma Loop_Variant (Increases => X, Decreases => Y); -@end example - -specifies that each time through the loop either X increases, or X stays -the same and Y decreases. A @code{Loop_Variant} pragma ensures that the -loop is making progress. It can be useful in helping to show informally -or prove formally that the loop always terminates. - -@code{Loop_Variant} is an assertion whose effect can be controlled using -an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The -policy can be @code{Check} to enable the loop variant check, @code{Ignore} -to ignore the check (in which case the pragma has no effect on the program), -or @code{Disable} in which case the pragma is not even checked for correct -syntax. - -Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that -apply to the same loop should be grouped in the same sequence of -statements. - -The @code{Loop_Entry} attribute may be used within the expressions of the -@code{Loop_Variant} pragma to refer to values on entry to the loop. - -@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{98} -@section Pragma Machine_Attribute - - -Syntax: - -@example -pragma Machine_Attribute ( - [Entity =>] LOCAL_NAME, - [Attribute_Name =>] static_string_EXPRESSION - [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] ); -@end example - -Machine-dependent attributes can be specified for types and/or -declarations. This pragma is semantically equivalent to -@code{__attribute__((@var{attribute_name}))} (if @code{info} is not -specified) or @code{__attribute__((@var{attribute_name(info})))} -or @code{__attribute__((@var{attribute_name(info,...})))} in GNU C, -where `attribute_name' is recognized by the compiler middle-end -or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note -that a string literal for the optional parameter @code{info} or the -following ones is transformed by default into an identifier, -which may make this pragma unusable for some attributes. -For further information see @cite{GNU Compiler Collection (GCC) Internals}. - -@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{99} -@section Pragma Main - - -Syntax: - -@example -pragma Main - (MAIN_OPTION [, MAIN_OPTION]); - -MAIN_OPTION ::= - [Stack_Size =>] static_integer_EXPRESSION -| [Task_Stack_Size_Default =>] static_integer_EXPRESSION -| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION -@end example - -This pragma is provided for compatibility with OpenVMS VAX Systems. It has -no effect in GNAT, other than being syntax checked. - -@node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9a} -@section Pragma Main_Storage - - -Syntax: - -@example -pragma Main_Storage - (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); - -MAIN_STORAGE_OPTION ::= - [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION -| [TOP_GUARD =>] static_SIMPLE_EXPRESSION -@end example - -This pragma is provided for compatibility with OpenVMS VAX Systems. It has -no effect in GNAT, other than being syntax checked. - -@node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9b}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9c} -@section Pragma Max_Queue_Length - - -Syntax: - -@example -pragma Max_Entry_Queue (static_integer_EXPRESSION); -@end example - -This pragma is used to specify the maximum callers per entry queue for -individual protected entries and entry families. It accepts a single -integer (-1 or more) as a parameter and must appear after the declaration of an -entry. - -A value of -1 represents no additional restriction on queue length. - -@node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9d} -@section Pragma No_Body - - -Syntax: - -@example -pragma No_Body; -@end example - -There are a number of cases in which a package spec does not require a body, -and in fact a body is not permitted. GNAT will not permit the spec to be -compiled if there is a body around. The pragma No_Body allows you to provide -a body file, even in a case where no body is allowed. The body file must -contain only comments and a single No_Body pragma. This is recognized by -the compiler as indicating that no body is logically present. - -This is particularly useful during maintenance when a package is modified in -such a way that a body needed before is no longer needed. The provision of a -dummy body with a No_Body pragma ensures that there is no interference from -earlier versions of the package body. - -@node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9e}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{9f} -@section Pragma No_Caching - - -Syntax: - -@example -pragma No_Caching [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{No_Caching} in -the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a0} -@section Pragma No_Component_Reordering - - -Syntax: - -@example -pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; -@end example - -@code{type_LOCAL_NAME} must refer to a record type declaration in the current -declarative part. The effect is to preclude any reordering of components -for the layout of the record, i.e. the record is laid out by the compiler -in the order in which the components are declared textually. The form with -no argument is a configuration pragma which applies to all record types -declared in units to which the pragma applies and there is a requirement -that this pragma be used consistently within a partition. - -@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a1}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a2} -@section Pragma No_Elaboration_Code_All - - -Syntax: - -@example -pragma No_Elaboration_Code_All [(program_unit_NAME)]; -@end example - -This is a program unit pragma (there is also an equivalent aspect of the -same name) that establishes the restriction @code{No_Elaboration_Code} for -the current unit and any extended main source units (body and subunits). -It also has the effect of enforcing a transitive application of this -aspect, so that if any unit is implicitly or explicitly with’ed by the -current unit, it must also have the No_Elaboration_Code_All aspect set. -It may be applied to package or subprogram specs or their generic versions. - -@node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a3} -@section Pragma No_Heap_Finalization - - -Syntax: - -@example -pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; -@end example - -Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a -type-specific pragma. - -In its configuration form, the pragma must appear within a configuration file -such as gnat.adc, without an argument. The pragma suppresses the call to -@code{Finalize} for heap-allocated objects created through library-level named -access-to-object types in cases where the designated type requires finalization -actions. - -In its type-specific form, the argument of the pragma must denote a -library-level named access-to-object type. The pragma suppresses the call to -@code{Finalize} for heap-allocated objects created through the specific access type -in cases where the designated type requires finalization actions. - -It is still possible to finalize such heap-allocated objects by explicitly -deallocating them. - -A library-level named access-to-object type declared within a generic unit will -lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not -appear at the library level. - -@node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a4}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a5} -@section Pragma No_Inline - - -Syntax: - -@example -pragma No_Inline (NAME @{, NAME@}); -@end example - -This pragma suppresses inlining for the callable entity or the instances of -the generic subprogram designated by @code{NAME}, including inlining that -results from the use of pragma @code{Inline}. This pragma is always active, -in particular it is not subject to the use of option `-gnatn' or -`-gnatN'. It is illegal to specify both pragma @code{No_Inline} and -pragma @code{Inline_Always} for the same @code{NAME}. - -@node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a6} -@section Pragma No_Return - - -Syntax: - -@example -pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); -@end example - -Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure -declarations in the current declarative part. A procedure to which this -pragma is applied may not contain any explicit @code{return} statements. -In addition, if the procedure contains any implicit returns from falling -off the end of a statement sequence, then execution of that implicit -return will cause Program_Error to be raised. - -One use of this pragma is to identify procedures whose only purpose is to raise -an exception. Another use of this pragma is to suppress incorrect warnings -about missing returns in functions, where the last statement of a function -statement sequence is a call to such a procedure. - -Note that in Ada 2005 mode, this pragma is part of the language. It is -available in all earlier versions of Ada as an implementation-defined -pragma. - -@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a7} -@section Pragma No_Strict_Aliasing - - -Syntax: - -@example -pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; -@end example - -@code{type_LOCAL_NAME} must refer to an access type -declaration in the current declarative part. The effect is to inhibit -strict aliasing optimization for the given type. The form with no -arguments is a configuration pragma which applies to all access types -declared in units to which the pragma applies. For a detailed -description of the strict aliasing optimization, and the situations -in which it must be suppressed, see the section on Optimization and Strict Aliasing -in the @cite{GNAT User’s Guide}. - -This pragma currently has no effects on access to unconstrained array types. - -@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{a8}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{a9} -@section Pragma No_Tagged_Streams - - -Syntax: - -@example -pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; -@end example - -Normally when a tagged type is introduced using a full type declaration, -part of the processing includes generating stream access routines to be -used by stream attributes referencing the type (or one of its subtypes -or derived types). This can involve the generation of significant amounts -of code which is wasted space if stream routines are not needed for the -type in question. - -The @code{No_Tagged_Streams} pragma causes the generation of these stream -routines to be skipped, and any attempt to use stream operations on -types subject to this pragma will be statically rejected as illegal. - -There are two forms of the pragma. The form with no arguments must appear -in a declarative sequence or in the declarations of a package spec. This -pragma affects all subsequent root tagged types declared in the declaration -sequence, and specifies that no stream routines be generated. The form with -an argument (for which there is also a corresponding aspect) specifies a -single root tagged type for which stream routines are not to be generated. - -Once the pragma has been given for a particular root tagged type, all subtypes -and derived types of this type inherit the pragma automatically, so the effect -applies to a complete hierarchy (this is necessary to deal with the class-wide -dispatching versions of the stream routines). - -When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously -applied to a tagged type its Expanded_Name and External_Tag are initialized -with empty strings. This is useful to avoid exposing entity names at binary -level but has a negative impact on the debuggability of tagged types. - -@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{aa} -@section Pragma Normalize_Scalars - - -Syntax: - -@example -pragma Normalize_Scalars; -@end example - -This is a language defined pragma which is fully implemented in GNAT. The -effect is to cause all scalar objects that are not otherwise initialized -to be initialized. The initial values are implementation dependent and -are as follows: - - -@table @asis - -@item `Standard.Character' - -Objects whose root type is Standard.Character are initialized to -Character’Last unless the subtype range excludes NUL (in which case -NUL is used). This choice will always generate an invalid value if -one exists. - -@item `Standard.Wide_Character' - -Objects whose root type is Standard.Wide_Character are initialized to -Wide_Character’Last unless the subtype range excludes NUL (in which case -NUL is used). This choice will always generate an invalid value if -one exists. - -@item `Standard.Wide_Wide_Character' - -Objects whose root type is Standard.Wide_Wide_Character are initialized to -the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in -which case NUL is used). This choice will always generate an invalid value if -one exists. - -@item `Integer types' - -Objects of an integer type are treated differently depending on whether -negative values are present in the subtype. If no negative values are -present, then all one bits is used as the initial value except in the -special case where zero is excluded from the subtype, in which case -all zero bits are used. This choice will always generate an invalid -value if one exists. - -For subtypes with negative values present, the largest negative number -is used, except in the unusual case where this largest negative number -is in the subtype, and the largest positive number is not, in which case -the largest positive value is used. This choice will always generate -an invalid value if one exists. - -@item `Floating-Point Types' - -Objects of all floating-point types are initialized to all 1-bits. For -standard IEEE format, this corresponds to a NaN (not a number) which is -indeed an invalid value. - -@item `Fixed-Point Types' - -Objects of all fixed-point types are treated as described above for integers, -with the rules applying to the underlying integer value used to represent -the fixed-point value. - -@item `Modular types' - -Objects of a modular type are initialized to all one bits, except in -the special case where zero is excluded from the subtype, in which -case all zero bits are used. This choice will always generate an -invalid value if one exists. - -@item `Enumeration types' - -Objects of an enumeration type are initialized to all one-bits, i.e., to -the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal -whose Pos value is zero, in which case a code of zero is used. This choice -will always generate an invalid value if one exists. -@end table - -@node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ab}@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{ac} -@section Pragma Obsolescent - - -Syntax: - -@example -pragma Obsolescent; - -pragma Obsolescent ( - [Message =>] static_string_EXPRESSION -[,[Version =>] Ada_05]); - -pragma Obsolescent ( - [Entity =>] NAME -[,[Message =>] static_string_EXPRESSION -[,[Version =>] Ada_05]]); -@end example - -This pragma can occur immediately following a declaration of an entity, -including the case of a record component. If no Entity argument is present, -then this declaration is the one to which the pragma applies. If an Entity -parameter is present, it must either match the name of the entity in this -declaration, or alternatively, the pragma can immediately follow an enumeration -type declaration, where the Entity argument names one of the enumeration -literals. - -This pragma is used to indicate that the named entity -is considered obsolescent and should not be used. Typically this is -used when an API must be modified by eventually removing or modifying -existing subprograms or other entities. The pragma can be used at an -intermediate stage when the entity is still present, but will be -removed later. - -The effect of this pragma is to output a warning message on a reference to -an entity thus marked that the subprogram is obsolescent if the appropriate -warning option in the compiler is activated. If the @code{Message} parameter is -present, then a second warning message is given containing this text. In -addition, a reference to the entity is considered to be a violation of pragma -@code{Restrictions (No_Obsolescent_Features)}. - -This pragma can also be used as a program unit pragma for a package, -in which case the entity name is the name of the package, and the -pragma indicates that the entire package is considered -obsolescent. In this case a client @code{with}ing such a package -violates the restriction, and the @code{with} clause is -flagged with warnings if the warning option is set. - -If the @code{Version} parameter is present (which must be exactly -the identifier @code{Ada_05}, no other argument is allowed), then the -indication of obsolescence applies only when compiling in Ada 2005 -mode. This is primarily intended for dealing with the situations -in the predefined library where subprograms or packages -have become defined as obsolescent in Ada 2005 -(e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. - -The following examples show typical uses of this pragma: - -@example -package p is - pragma Obsolescent (p, Message => "use pp instead of p"); -end p; - -package q is - procedure q2; - pragma Obsolescent ("use q2new instead"); - - type R is new integer; - pragma Obsolescent - (Entity => R, - Message => "use RR in Ada 2005", - Version => Ada_05); - - type M is record - F1 : Integer; - F2 : Integer; - pragma Obsolescent; - F3 : Integer; - end record; - - type E is (a, bc, 'd', quack); - pragma Obsolescent (Entity => bc) - pragma Obsolescent (Entity => 'd') - - function "+" - (a, b : character) return character; - pragma Obsolescent (Entity => "+"); -end; -@end example - -Note that, as for all pragmas, if you use a pragma argument identifier, -then all subsequent parameters must also use a pragma argument identifier. -So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} -argument is present, it must be preceded by @code{Message =>}. - -@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{ad} -@section Pragma Optimize_Alignment - - -@geindex Alignment -@geindex default settings - -Syntax: - -@example -pragma Optimize_Alignment (TIME | SPACE | OFF); -@end example - -This is a configuration pragma which affects the choice of default alignments -for types and objects where no alignment is explicitly specified. There is a -time/space trade-off in the selection of these values. Large alignments result -in more efficient code, at the expense of larger data space, since sizes have -to be increased to match these alignments. Smaller alignments save space, but -the access code is slower. The normal choice of default alignments for types -and individual alignment promotions for objects (which is what you get if you -do not use this pragma, or if you use an argument of OFF), tries to balance -these two requirements. - -Specifying SPACE causes smaller default alignments to be chosen in two cases. -First any packed record is given an alignment of 1. Second, if a size is given -for the type, then the alignment is chosen to avoid increasing this size. For -example, consider: - -@example -type R is record - X : Integer; - Y : Character; -end record; - -for R'Size use 5*8; -@end example - -In the default mode, this type gets an alignment of 4, so that access to the -Integer field X are efficient. But this means that objects of the type end up -with a size of 8 bytes. This is a valid choice, since sizes of objects are -allowed to be bigger than the size of the type, but it can waste space if for -example fields of type R appear in an enclosing record. If the above type is -compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. - -However, there is one case in which SPACE is ignored. If a variable length -record (that is a discriminated record with a component which is an array -whose length depends on a discriminant), has a pragma Pack, then it is not -in general possible to set the alignment of such a record to one, so the -pragma is ignored in this case (with a warning). - -Specifying SPACE also disables alignment promotions for standalone objects, -which occur when the compiler increases the alignment of a specific object -without changing the alignment of its type. - -Specifying SPACE also disables component reordering in unpacked record types, -which can result in larger sizes in order to meet alignment requirements. - -Specifying TIME causes larger default alignments to be chosen in the case of -small types with sizes that are not a power of 2. For example, consider: - -@example -type R is record - A : Character; - B : Character; - C : Boolean; -end record; - -pragma Pack (R); -for R'Size use 17; -@end example - -The default alignment for this record is normally 1, but if this type is -compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set -to 4, which wastes space for objects of the type, since they are now 4 bytes -long, but results in more efficient access when the whole record is referenced. - -As noted above, this is a configuration pragma, and there is a requirement -that all units in a partition be compiled with a consistent setting of the -optimization setting. This would normally be achieved by use of a configuration -pragma file containing the appropriate setting. The exception to this rule is -that units with an explicit configuration pragma in the same file as the source -unit are excluded from the consistency check, as are all predefined units. The -latter are compiled by default in pragma Optimize_Alignment (Off) mode if no -pragma appears at the start of the file. - -@node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{ae} -@section Pragma Ordered - - -Syntax: - -@example -pragma Ordered (enumeration_first_subtype_LOCAL_NAME); -@end example - -Most enumeration types are from a conceptual point of view unordered. -For example, consider: - -@example -type Color is (Red, Blue, Green, Yellow); -@end example - -By Ada semantics @code{Blue > Red} and @code{Green > Blue}, -but really these relations make no sense; the enumeration type merely -specifies a set of possible colors, and the order is unimportant. - -For unordered enumeration types, it is generally a good idea if -clients avoid comparisons (other than equality or inequality) and -explicit ranges. (A `client' is a unit where the type is referenced, -other than the unit where the type is declared, its body, and its subunits.) -For example, if code buried in some client says: - -@example -if Current_Color < Yellow then ... -if Current_Color in Blue .. Green then ... -@end example - -then the client code is relying on the order, which is undesirable. -It makes the code hard to read and creates maintenance difficulties if -entries have to be added to the enumeration type. Instead, -the code in the client should list the possibilities, or an -appropriate subtype should be declared in the unit that declares -the original enumeration type. E.g., the following subtype could -be declared along with the type @code{Color}: - -@example -subtype RBG is Color range Red .. Green; -@end example - -and then the client could write: - -@example -if Current_Color in RBG then ... -if Current_Color = Blue or Current_Color = Green then ... -@end example - -However, some enumeration types are legitimately ordered from a conceptual -point of view. For example, if you declare: - -@example -type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); -@end example - -then the ordering imposed by the language is reasonable, and -clients can depend on it, writing for example: - -@example -if D in Mon .. Fri then ... -if D < Wed then ... -@end example - -The pragma `Ordered' is provided to mark enumeration types that -are conceptually ordered, alerting the reader that clients may depend -on the ordering. GNAT provides a pragma to mark enumerations as ordered -rather than one to mark them as unordered, since in our experience, -the great majority of enumeration types are conceptually unordered. - -The types @code{Boolean}, @code{Character}, @code{Wide_Character}, -and @code{Wide_Wide_Character} -are considered to be ordered types, so each is declared with a -pragma @code{Ordered} in package @code{Standard}. - -Normally pragma @code{Ordered} serves only as documentation and a guide for -coding standards, but GNAT provides a warning switch `-gnatw.u' that -requests warnings for inappropriate uses (comparisons and explicit -subranges) for unordered types. If this switch is used, then any -enumeration type not marked with pragma @code{Ordered} will be considered -as unordered, and will generate warnings for inappropriate uses. - -Note that generic types are not considered ordered or unordered (since the -template can be instantiated for both cases), so we never generate warnings -for the case of generic enumerated types. - -For additional information please refer to the description of the -`-gnatw.u' switch in the GNAT User’s Guide. - -@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{af} -@section Pragma Overflow_Mode - - -Syntax: - -@example -pragma Overflow_Mode - ( [General =>] MODE - [,[Assertions =>] MODE]); - -MODE ::= STRICT | MINIMIZED | ELIMINATED -@end example - -This pragma sets the current overflow mode to the given setting. For details -of the meaning of these modes, please refer to the -‘Overflow Check Handling in GNAT’ appendix in the -GNAT User’s Guide. If only the @code{General} parameter is present, -the given mode applies to all expressions. If both parameters are present, -the @code{General} mode applies to expressions outside assertions, and -the @code{Eliminated} mode applies to expressions within assertions. - -The case of the @code{MODE} parameter is ignored, -so @code{MINIMIZED}, @code{Minimized} and -@code{minimized} all have the same effect. - -The @code{Overflow_Mode} pragma has the same scoping and placement -rules as pragma @code{Suppress}, so it can occur either as a -configuration pragma, specifying a default for the whole -program, or in a declarative scope, where it applies to the -remaining declarations and statements in that scope. - -The pragma @code{Suppress (Overflow_Check)} suppresses -overflow checking, but does not affect the overflow mode. - -The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) -overflow checking, but does not affect the overflow mode. - -@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b0} -@section Pragma Overriding_Renamings - - -@geindex Rational profile - -@geindex Rational compatibility - -Syntax: - -@example -pragma Overriding_Renamings; -@end example - -This is a GNAT configuration pragma to simplify porting -legacy code accepted by the Rational -Ada compiler. In the presence of this pragma, a renaming declaration that -renames an inherited operation declared in the same scope is legal if selected -notation is used as in: - -@example -pragma Overriding_Renamings; -... -package R is - function F (..); - ... - function F (..) renames R.F; -end R; -@end example - -even though -RM 8.3 (15) stipulates that an overridden operation is not visible within the -declaration of the overriding operation. - -@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b1} -@section Pragma Partition_Elaboration_Policy - - -Syntax: - -@example -pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); - -POLICY_IDENTIFIER ::= Concurrent | Sequential -@end example - -This pragma is standard in Ada 2005, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b2}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b3} -@section Pragma Part_Of - - -Syntax: - -@example -pragma Part_Of (ABSTRACT_STATE); - -ABSTRACT_STATE ::= NAME -@end example - -For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the -SPARK 2014 Reference Manual, section 7.2.6. - -@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b4} -@section Pragma Passive - - -Syntax: - -@example -pragma Passive [(Semaphore | No)]; -@end example - -Syntax checked, but otherwise ignored by GNAT. This is recognized for -compatibility with DEC Ada 83 implementations, where it is used within a -task definition to request that a task be made passive. If the argument -@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 -treats the pragma as an assertion that the containing task is passive -and that optimization of context switch with this task is permitted and -desired. If the argument @code{No} is present, the task must not be -optimized. GNAT does not attempt to optimize any tasks in this manner -(since protected objects are available in place of passive tasks). - -For more information on the subject of passive tasks, see the section -‘Passive Task Optimization’ in the GNAT Users Guide. - -@node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b5}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b6} -@section Pragma Persistent_BSS - - -Syntax: - -@example -pragma Persistent_BSS [(LOCAL_NAME)] -@end example - -This pragma allows selected objects to be placed in the @code{.persistent_bss} -section. On some targets the linker and loader provide for special -treatment of this section, allowing a program to be reloaded without -affecting the contents of this data (hence the name persistent). - -There are two forms of usage. If an argument is given, it must be the -local name of a library-level object, with no explicit initialization -and whose type is potentially persistent. If no argument is given, then -the pragma is a configuration pragma, and applies to all library-level -objects with no explicit initialization of potentially persistent types. - -A potentially persistent type is a scalar type, or an untagged, -non-discriminated record, all of whose components have no explicit -initialization and are themselves of a potentially persistent type, -or an array, all of whose constraints are static, and whose component -type is potentially persistent. - -If this pragma is used on a target where this feature is not supported, -then the pragma will be ignored. See also @code{pragma Linker_Section}. - -@node Pragma Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b7} -@section Pragma Post - - -@geindex Post - -@geindex Checks -@geindex postconditions - -Syntax: - -@example -pragma Post (Boolean_Expression); -@end example - -The @code{Post} pragma is intended to be an exact replacement for -the language-defined -@code{Post} aspect, and shares its restrictions and semantics. -It must appear either immediately following the corresponding -subprogram declaration (only other pragmas may intervene), or -if there is no separate subprogram declaration, then it can -appear at the start of the declarations in a subprogram body -(preceded only by other pragmas). - -@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{b8} -@section Pragma Postcondition - - -@geindex Postcondition - -@geindex Checks -@geindex postconditions - -Syntax: - -@example -pragma Postcondition ( - [Check =>] Boolean_Expression - [,[Message =>] String_Expression]); -@end example - -The @code{Postcondition} pragma allows specification of automatic -postcondition checks for subprograms. These checks are similar to -assertions, but are automatically inserted just prior to the return -statements of the subprogram with which they are associated (including -implicit returns at the end of procedure bodies and associated -exception handlers). - -In addition, the boolean expression which is the condition which -must be true may contain references to function’Result in the case -of a function to refer to the returned value. - -@code{Postcondition} pragmas may appear either immediately following the -(separate) declaration of a subprogram, or at the start of the -declarations of a subprogram body. Only other pragmas may intervene -(that is appear between the subprogram declaration and its -postconditions, or appear before the postcondition in the -declaration sequence in a subprogram body). In the case of a -postcondition appearing after a subprogram declaration, the -formal arguments of the subprogram are visible, and can be -referenced in the postcondition expressions. - -The postconditions are collected and automatically tested just -before any return (implicit or explicit) in the subprogram body. -A postcondition is only recognized if postconditions are active -at the time the pragma is encountered. The compiler switch `gnata' -turns on all postconditions by default, and pragma @code{Check_Policy} -with an identifier of @code{Postcondition} can also be used to -control whether postconditions are active. - -The general approach is that postconditions are placed in the spec -if they represent functional aspects which make sense to the client. -For example we might have: - -@example -function Direction return Integer; -pragma Postcondition - (Direction'Result = +1 - or else - Direction'Result = -1); -@end example - -which serves to document that the result must be +1 or -1, and -will test that this is the case at run time if postcondition -checking is active. - -Postconditions within the subprogram body can be used to -check that some internal aspect of the implementation, -not visible to the client, is operating as expected. -For instance if a square root routine keeps an internal -counter of the number of times it is called, then we -might have the following postcondition: - -@example -Sqrt_Calls : Natural := 0; - -function Sqrt (Arg : Float) return Float is - pragma Postcondition - (Sqrt_Calls = Sqrt_Calls'Old + 1); - ... -end Sqrt -@end example - -As this example, shows, the use of the @code{Old} attribute -is often useful in postconditions to refer to the state on -entry to the subprogram. - -Note that postconditions are only checked on normal returns -from the subprogram. If an abnormal return results from -raising an exception, then the postconditions are not checked. - -If a postcondition fails, then the exception -@code{System.Assertions.Assert_Failure} is raised. If -a message argument was supplied, then the given string -will be used as the exception message. If no message -argument was supplied, then the default message has -the form “Postcondition failed at file_name:line”. The -exception is raised in the context of the subprogram -body, so it is possible to catch postcondition failures -within the subprogram body itself. - -Within a package spec, normal visibility rules -in Ada would prevent forward references within a -postcondition pragma to functions defined later in -the same package. This would introduce undesirable -ordering constraints. To avoid this problem, all -postcondition pragmas are analyzed at the end of -the package spec, allowing forward references. - -The following example shows that this even allows -mutually recursive postconditions as in: - -@example -package Parity_Functions is - function Odd (X : Natural) return Boolean; - pragma Postcondition - (Odd'Result = - (x = 1 - or else - (x /= 0 and then Even (X - 1)))); - - function Even (X : Natural) return Boolean; - pragma Postcondition - (Even'Result = - (x = 0 - or else - (x /= 1 and then Odd (X - 1)))); - -end Parity_Functions; -@end example - -There are no restrictions on the complexity or form of -conditions used within @code{Postcondition} pragmas. -The following example shows that it is even possible -to verify performance behavior. - -@example -package Sort is - - Performance : constant Float; - -- Performance constant set by implementation - -- to match target architecture behavior. - - procedure Treesort (Arg : String); - -- Sorts characters of argument using N*logN sort - pragma Postcondition - (Float (Clock - Clock'Old) <= - Float (Arg'Length) * - log (Float (Arg'Length)) * - Performance); -end Sort; -@end example - -Note: postcondition pragmas associated with subprograms that are -marked as Inline_Always, or those marked as Inline with front-end -inlining (-gnatN option set) are accepted and legality-checked -by the compiler, but are ignored at run-time even if postcondition -checking is enabled. - -Note that pragma @code{Postcondition} differs from the language-defined -@code{Post} aspect (and corresponding @code{Post} pragma) in allowing -multiple occurrences, allowing occurences in the body even if there -is a separate spec, and allowing a second string parameter, and the -use of the pragma identifier @code{Check}. Historically, pragma -@code{Postcondition} was implemented prior to the development of -Ada 2012, and has been retained in its original form for -compatibility purposes. - -@node Pragma Post_Class,Pragma Pre,Pragma Postcondition,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{b9} -@section Pragma Post_Class - - -@geindex Post - -@geindex Checks -@geindex postconditions - -Syntax: - -@example -pragma Post_Class (Boolean_Expression); -@end example - -The @code{Post_Class} pragma is intended to be an exact replacement for -the language-defined -@code{Post'Class} aspect, and shares its restrictions and semantics. -It must appear either immediately following the corresponding -subprogram declaration (only other pragmas may intervene), or -if there is no separate subprogram declaration, then it can -appear at the start of the declarations in a subprogram body -(preceded only by other pragmas). - -Note: This pragma is called @code{Post_Class} rather than -@code{Post'Class} because the latter would not be strictly -conforming to the allowed syntax for pragmas. The motivation -for providing pragmas equivalent to the aspects is to allow a program -to be written using the pragmas, and then compiled if necessary -using an Ada compiler that does not recognize the pragmas or -aspects, but is prepared to ignore the pragmas. The assertion -policy that controls this pragma is @code{Post'Class}, not -@code{Post_Class}. - -@node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{ba} -@section Pragma Pre - - -@geindex Pre - -@geindex Checks -@geindex preconditions - -Syntax: - -@example -pragma Pre (Boolean_Expression); -@end example - -The @code{Pre} pragma is intended to be an exact replacement for -the language-defined -@code{Pre} aspect, and shares its restrictions and semantics. -It must appear either immediately following the corresponding -subprogram declaration (only other pragmas may intervene), or -if there is no separate subprogram declaration, then it can -appear at the start of the declarations in a subprogram body -(preceded only by other pragmas). - -@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bb} -@section Pragma Precondition - - -@geindex Preconditions - -@geindex Checks -@geindex preconditions - -Syntax: - -@example -pragma Precondition ( - [Check =>] Boolean_Expression - [,[Message =>] String_Expression]); -@end example - -The @code{Precondition} pragma is similar to @code{Postcondition} -except that the corresponding checks take place immediately upon -entry to the subprogram, and if a precondition fails, the exception -is raised in the context of the caller, and the attribute ‘Result -cannot be used within the precondition expression. - -Otherwise, the placement and visibility rules are identical to those -described for postconditions. The following is an example of use -within a package spec: - -@example -package Math_Functions is - ... - function Sqrt (Arg : Float) return Float; - pragma Precondition (Arg >= 0.0) - ... -end Math_Functions; -@end example - -@code{Precondition} pragmas may appear either immediately following the -(separate) declaration of a subprogram, or at the start of the -declarations of a subprogram body. Only other pragmas may intervene -(that is appear between the subprogram declaration and its -postconditions, or appear before the postcondition in the -declaration sequence in a subprogram body). - -Note: precondition pragmas associated with subprograms that are -marked as Inline_Always, or those marked as Inline with front-end -inlining (-gnatN option set) are accepted and legality-checked -by the compiler, but are ignored at run-time even if precondition -checking is enabled. - -Note that pragma @code{Precondition} differs from the language-defined -@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing -multiple occurrences, allowing occurences in the body even if there -is a separate spec, and allowing a second string parameter, and the -use of the pragma identifier @code{Check}. Historically, pragma -@code{Precondition} was implemented prior to the development of -Ada 2012, and has been retained in its original form for -compatibility purposes. - -@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{bc}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{bd} -@section Pragma Predicate - - -Syntax: - -@example -pragma Predicate - ([Entity =>] type_LOCAL_NAME, - [Check =>] EXPRESSION); -@end example - -This pragma (available in all versions of Ada in GNAT) encompasses both -the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in -Ada 2012. A predicate is regarded as static if it has an allowed form -for @code{Static_Predicate} and is otherwise treated as a -@code{Dynamic_Predicate}. Otherwise, predicates specified by this -pragma behave exactly as described in the Ada 2012 reference manual. -For example, if we have - -@example -type R is range 1 .. 10; -subtype S is R; -pragma Predicate (Entity => S, Check => S not in 4 .. 6); -subtype Q is R -pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); -@end example - -the effect is identical to the following Ada 2012 code: - -@example -type R is range 1 .. 10; -subtype S is R with - Static_Predicate => S not in 4 .. 6; -subtype Q is R with - Dynamic_Predicate => F(Q) or G(Q); -@end example - -Note that there are no pragmas @code{Dynamic_Predicate} -or @code{Static_Predicate}. That is -because these pragmas would affect legality and semantics of -the program and thus do not have a neutral effect if ignored. -The motivation behind providing pragmas equivalent to -corresponding aspects is to allow a program to be written -using the pragmas, and then compiled with a compiler that -will ignore the pragmas. That doesn’t work in the case of -static and dynamic predicates, since if the corresponding -pragmas are ignored, then the behavior of the program is -fundamentally changed (for example a membership test -@code{A in B} would not take into account a predicate -defined for subtype B). When following this approach, the -use of predicates should be avoided. - -@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{be} -@section Pragma Predicate_Failure - - -Syntax: - -@example -pragma Predicate_Failure - ([Entity =>] type_LOCAL_NAME, - [Message =>] String_Expression); -@end example - -The @code{Predicate_Failure} pragma is intended to be an exact replacement for -the language-defined -@code{Predicate_Failure} aspect, and shares its restrictions and semantics. - -@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{bf} -@section Pragma Preelaborable_Initialization - - -Syntax: - -@example -pragma Preelaborable_Initialization (DIRECT_NAME); -@end example - -This pragma is standard in Ada 2005, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c0} -@section Pragma Prefix_Exception_Messages - - -@geindex Prefix_Exception_Messages - -@geindex exception - -@geindex Exception_Message - -Syntax: - -@example -pragma Prefix_Exception_Messages; -@end example - -This is an implementation-defined configuration pragma that affects the -behavior of raise statements with a message given as a static string -constant (typically a string literal). In such cases, the string will -be automatically prefixed by the name of the enclosing entity (giving -the package and subprogram containing the raise statement). This helps -to identify where messages are coming from, and this mode is automatic -for the run-time library. - -The pragma has no effect if the message is computed with an expression other -than a static string constant, since the assumption in this case is that -the program computes exactly the string it wants. If you still want the -prefixing in this case, you can always call -@code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. - -@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c1} -@section Pragma Pre_Class - - -@geindex Pre_Class - -@geindex Checks -@geindex preconditions - -Syntax: - -@example -pragma Pre_Class (Boolean_Expression); -@end example - -The @code{Pre_Class} pragma is intended to be an exact replacement for -the language-defined -@code{Pre'Class} aspect, and shares its restrictions and semantics. -It must appear either immediately following the corresponding -subprogram declaration (only other pragmas may intervene), or -if there is no separate subprogram declaration, then it can -appear at the start of the declarations in a subprogram body -(preceded only by other pragmas). - -Note: This pragma is called @code{Pre_Class} rather than -@code{Pre'Class} because the latter would not be strictly -conforming to the allowed syntax for pragmas. The motivation -for providing pragmas equivalent to the aspects is to allow a program -to be written using the pragmas, and then compiled if necessary -using an Ada compiler that does not recognize the pragmas or -aspects, but is prepared to ignore the pragmas. The assertion -policy that controls this pragma is @code{Pre'Class}, not -@code{Pre_Class}. - -@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c2} -@section Pragma Priority_Specific_Dispatching - - -Syntax: - -@example -pragma Priority_Specific_Dispatching ( - POLICY_IDENTIFIER, - first_priority_EXPRESSION, - last_priority_EXPRESSION) - -POLICY_IDENTIFIER ::= - EDF_Across_Priorities | - FIFO_Within_Priorities | - Non_Preemptive_Within_Priorities | - Round_Robin_Within_Priorities -@end example - -This pragma is standard in Ada 2005, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c3} -@section Pragma Profile - - -Syntax: - -@example -pragma Profile (Ravenscar | Restricted | Rational | Jorvik | - GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); -@end example - -This pragma is standard in Ada 2005, but is available in all earlier -versions of Ada as an implementation-defined pragma. This is a -configuration pragma that establishes a set of configuration pragmas -that depend on the argument. @code{Ravenscar} is standard in Ada 2005. -@code{Jorvik} is standard in Ada 202x. -The other possibilities (@code{Restricted}, @code{Rational}, -@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) -are implementation-defined. @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}. - -The set of configuration pragmas is defined in the following sections. - - -@itemize * - -@item -Pragma Profile (Ravenscar) - -The @code{Ravenscar} profile is standard in Ada 2005, -but is available in all earlier -versions of Ada as an implementation-defined pragma. This profile -establishes the following set of configuration pragmas: - - -@itemize * - -@item -@code{Task_Dispatching_Policy (FIFO_Within_Priorities)} - -[RM D.2.2] Tasks are dispatched following a preemptive -priority-ordered scheduling policy. - -@item -@code{Locking_Policy (Ceiling_Locking)} - -[RM D.3] While tasks and interrupts execute a protected action, they inherit -the ceiling priority of the corresponding protected object. - -@item -@code{Detect_Blocking} - -This pragma forces the detection of potentially blocking operations within a -protected operation, and to raise Program_Error if that happens. -@end itemize - -plus the following set of restrictions: - - -@itemize * - -@item -@code{Max_Entry_Queue_Length => 1} - -No task can be queued on a protected entry. - -@item -@code{Max_Protected_Entries => 1} - -@item -@code{Max_Task_Entries => 0} - -No rendezvous statements are allowed. - -@item -@code{No_Abort_Statements} - -@item -@code{No_Dynamic_Attachment} - -@item -@code{No_Dynamic_Priorities} - -@item -@code{No_Implicit_Heap_Allocations} - -@item -@code{No_Local_Protected_Objects} - -@item -@code{No_Local_Timing_Events} - -@item -@code{No_Protected_Type_Allocators} - -@item -@code{No_Relative_Delay} - -@item -@code{No_Requeue_Statements} - -@item -@code{No_Select_Statements} - -@item -@code{No_Specific_Termination_Handlers} - -@item -@code{No_Task_Allocators} - -@item -@code{No_Task_Hierarchy} - -@item -@code{No_Task_Termination} - -@item -@code{Simple_Barriers} -@end itemize - -The Ravenscar profile also includes the following restrictions that specify -that there are no semantic dependencies on the corresponding predefined -packages: - - -@itemize * - -@item -@code{No_Dependence => Ada.Asynchronous_Task_Control} - -@item -@code{No_Dependence => Ada.Calendar} - -@item -@code{No_Dependence => Ada.Execution_Time.Group_Budget} - -@item -@code{No_Dependence => Ada.Execution_Time.Timers} - -@item -@code{No_Dependence => Ada.Task_Attributes} - -@item -@code{No_Dependence => System.Multiprocessors.Dispatching_Domains} -@end itemize - -This set of configuration pragmas and restrictions correspond to the -definition of the ‘Ravenscar Profile’ for limited tasking, devised and -published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. -A description is also available at -@indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. - -The original definition of the profile was revised at subsequent IRTAW -meetings. It has been included in the ISO -@cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, -and was made part of the Ada 2005 standard. -The formal definition given by -the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and -AI-305) available at -@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and -@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. - -The above set is a superset of the restrictions provided by pragma -@code{Profile (Restricted)}, it includes six additional restrictions -(@code{Simple_Barriers}, @code{No_Select_Statements}, -@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, -@code{No_Relative_Delay} and @code{No_Task_Termination}). This means -that pragma @code{Profile (Ravenscar)}, like the pragma -@code{Profile (Restricted)}, -automatically causes the use of a simplified, -more efficient version of the tasking run-time library. - -@item -Pragma Profile (Jorvik) - -@code{Jorvik} is the new profile added to the Ada 202x draft standard, -previously implemented under the name @code{GNAT_Extended_Ravenscar}. - -The @code{No_Implicit_Heap_Allocations} restriction has been replaced -by @code{No_Implicit_Task_Allocations} and -@code{No_Implicit_Protected_Object_Allocations}. - -The @code{Simple_Barriers} restriction has been replaced by -@code{Pure_Barriers}. - -The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and -@code{No_Relative_Delay} restrictions have been removed. - -Details on the rationale for @code{Jorvik} and implications for use may be -found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz, -T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies – Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science, -Number 10300. - -@item -Pragma Profile (GNAT_Ravenscar_EDF) - -This profile corresponds to the Ravenscar profile but using -EDF_Across_Priority as the Task_Scheduling_Policy. - -@item -Pragma Profile (Restricted) - -This profile corresponds to the GNAT restricted run time. It -establishes the following set of restrictions: - - -@itemize * - -@item -@code{No_Abort_Statements} - -@item -@code{No_Entry_Queue} - -@item -@code{No_Task_Hierarchy} - -@item -@code{No_Task_Allocators} - -@item -@code{No_Dynamic_Priorities} - -@item -@code{No_Terminate_Alternatives} - -@item -@code{No_Dynamic_Attachment} - -@item -@code{No_Protected_Type_Allocators} - -@item -@code{No_Local_Protected_Objects} - -@item -@code{No_Requeue_Statements} - -@item -@code{No_Task_Attributes_Package} - -@item -@code{Max_Asynchronous_Select_Nesting = 0} - -@item -@code{Max_Task_Entries = 0} - -@item -@code{Max_Protected_Entries = 1} - -@item -@code{Max_Select_Alternatives = 0} -@end itemize - -This set of restrictions causes the automatic selection of a simplified -version of the run time that provides improved performance for the -limited set of tasking functionality permitted by this set of restrictions. - -@item -Pragma Profile (Rational) - -The Rational profile is intended to facilitate porting legacy code that -compiles with the Rational APEX compiler, even when the code includes non- -conforming Ada constructs. The profile enables the following three pragmas: - - -@itemize * - -@item -@code{pragma Implicit_Packing} - -@item -@code{pragma Overriding_Renamings} - -@item -@code{pragma Use_VADS_Size} -@end itemize -@end itemize - -@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c4} -@section Pragma Profile_Warnings - - -Syntax: - -@example -pragma Profile_Warnings (Ravenscar | Restricted | Rational); -@end example - -This is an implementation-defined pragma that is similar in -effect to @code{pragma Profile} except that instead of -generating @code{Restrictions} pragmas, it generates -@code{Restriction_Warnings} pragmas. The result is that -violations of the profile generate warning messages instead -of error messages. - -@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c5} -@section Pragma Propagate_Exceptions - - -@geindex Interfacing to C++ - -Syntax: - -@example -pragma Propagate_Exceptions; -@end example - -This pragma is now obsolete and, other than generating a warning if warnings -on obsolescent features are enabled, is ignored. -It is retained for compatibility -purposes. It used to be used in connection with optimization of -a now-obsolete mechanism for implementation of exceptions. - -@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c6} -@section Pragma Provide_Shift_Operators - - -@geindex Shift operators - -Syntax: - -@example -pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); -@end example - -This pragma can be applied to a first subtype local name that specifies -either an unsigned or signed type. It has the effect of providing the -five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, -Rotate_Left and Rotate_Right) for the given type. It is similar to -including the function declarations for these five operators, together -with the pragma Import (Intrinsic, …) statements. - -@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{c7} -@section Pragma Psect_Object - - -Syntax: - -@example -pragma Psect_Object ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -@end example - -This pragma is identical in effect to pragma @code{Common_Object}. - -@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{c8}@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{c9} -@section Pragma Pure_Function - - -Syntax: - -@example -pragma Pure_Function ([Entity =>] function_LOCAL_NAME); -@end example - -This pragma appears in the same declarative part as a function -declaration (or a set of function declarations if more than one -overloaded declaration exists, in which case the pragma applies -to all entities). It specifies that the function @code{Entity} is -to be considered pure for the purposes of code generation. This means -that the compiler can assume that there are no side effects, and -in particular that two identical calls produce the same result in -the same context. It also means that the function can be used in -an address clause. - -Note that, quite deliberately, there are no static checks to try -to ensure that this promise is met, so @code{Pure_Function} can be used -with functions that are conceptually pure, even if they do modify -global variables. For example, a square root function that is -instrumented to count the number of times it is called is still -conceptually pure, and can still be optimized, even though it -modifies a global variable (the count). Memo functions are another -example (where a table of previous calls is kept and consulted to -avoid re-computation). - -Note also that the normal rules excluding optimization of subprograms -in pure units (when parameter types are descended from System.Address, -or when the full view of a parameter type is limited), do not apply -for the Pure_Function case. If you explicitly specify Pure_Function, -the compiler may optimize away calls with identical arguments, and -if that results in unexpected behavior, the proper action is not to -use the pragma for subprograms that are not (conceptually) pure. - -Note: Most functions in a @code{Pure} package are automatically pure, and -there is no need to use pragma @code{Pure_Function} for such functions. One -exception is any function that has at least one formal of type -@code{System.Address} or a type derived from it. Such functions are not -considered pure by default, since the compiler assumes that the -@code{Address} parameter may be functioning as a pointer and that the -referenced data may change even if the address value does not. -Similarly, imported functions are not considered to be pure by default, -since there is no way of checking that they are in fact pure. The use -of pragma @code{Pure_Function} for such a function will override these default -assumption, and cause the compiler to treat a designated subprogram as pure -in these cases. - -Note: If pragma @code{Pure_Function} is applied to a renamed function, it -applies to the underlying renamed function. This can be used to -disambiguate cases of overloading where some but not all functions -in a set of overloaded functions are to be designated as pure. - -If pragma @code{Pure_Function} is applied to a library-level function, the -function is also considered pure from an optimization point of view, but the -unit is not a Pure unit in the categorization sense. So for example, a function -thus marked is free to @code{with} non-pure units. - -@node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{ca} -@section Pragma Rational - - -Syntax: - -@example -pragma Rational; -@end example - -This pragma is considered obsolescent, but is retained for -compatibility purposes. It is equivalent to: - -@example -pragma Profile (Rational); -@end example - -@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cb} -@section Pragma Ravenscar - - -Syntax: - -@example -pragma Ravenscar; -@end example - -This pragma is considered obsolescent, but is retained for -compatibility purposes. It is equivalent to: - -@example -pragma Profile (Ravenscar); -@end example - -which is the preferred method of setting the @code{Ravenscar} profile. - -@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cc}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{cd} -@section Pragma Refined_Depends - - -Syntax: - -@example -pragma Refined_Depends (DEPENDENCY_RELATION); - -DEPENDENCY_RELATION ::= - null - | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) - -DEPENDENCY_CLAUSE ::= - OUTPUT_LIST =>[+] INPUT_LIST - | NULL_DEPENDENCY_CLAUSE - -NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST - -OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) - -INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) - -OUTPUT ::= NAME | FUNCTION_RESULT -INPUT ::= NAME - -where FUNCTION_RESULT is a function Result attribute_reference -@end example - -For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in -the SPARK 2014 Reference Manual, section 6.1.5. - -@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{ce}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{cf} -@section Pragma Refined_Global - - -Syntax: - -@example -pragma Refined_Global (GLOBAL_SPECIFICATION); - -GLOBAL_SPECIFICATION ::= - null - | (GLOBAL_LIST) - | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) - -MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST - -MODE_SELECTOR ::= In_Out | Input | Output | Proof_In -GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) -GLOBAL_ITEM ::= NAME -@end example - -For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in -the SPARK 2014 Reference Manual, section 6.1.4. - -@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d0}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d1} -@section Pragma Refined_Post - - -Syntax: - -@example -pragma Refined_Post (boolean_EXPRESSION); -@end example - -For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in -the SPARK 2014 Reference Manual, section 7.2.7. - -@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d2}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d3} -@section Pragma Refined_State - - -Syntax: - -@example -pragma Refined_State (REFINEMENT_LIST); - -REFINEMENT_LIST ::= - (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) - -REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST - -CONSTITUENT_LIST ::= - null - | CONSTITUENT - | (CONSTITUENT @{, CONSTITUENT@}) - -CONSTITUENT ::= object_NAME | state_NAME -@end example - -For the semantics of this pragma, see the entry for aspect @code{Refined_State} in -the SPARK 2014 Reference Manual, section 7.2.2. - -@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d4} -@section Pragma Relative_Deadline - - -Syntax: - -@example -pragma Relative_Deadline (time_span_EXPRESSION); -@end example - -This pragma is standard in Ada 2005, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Remote_Access_Type,Pragma Rename_Pragma,Pragma Relative_Deadline,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d5}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d6} -@section Pragma Remote_Access_Type - - -Syntax: - -@example -pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); -@end example - -This pragma appears in the formal part of a generic declaration. -It specifies an exception to the RM rule from E.2.2(17/2), which forbids -the use of a remote access to class-wide type as actual for a formal -access type. - -When this pragma applies to a formal access type @code{Entity}, that -type is treated as a remote access to class-wide type in the generic. -It must be a formal general access type, and its designated type must -be the class-wide type of a formal tagged limited private type from the -same generic declaration. - -In the generic unit, the formal type is subject to all restrictions -pertaining to remote access to class-wide types. At instantiation, the -actual type must be a remote access to class-wide type. - -@node Pragma Rename_Pragma,Pragma Restricted_Run_Time,Pragma Remote_Access_Type,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{d7} -@section Pragma Rename_Pragma - - -@geindex Pragmas -@geindex synonyms - -Syntax: - -@example -pragma Rename_Pragma ( - [New_Name =>] IDENTIFIER, - [Renamed =>] pragma_IDENTIFIER); -@end example - -This pragma provides a mechanism for supplying new names for existing -pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for -the Renamed pragma. For example, suppose you have code that was originally -developed on a compiler that supports Inline_Only as an implementation defined -pragma. And suppose the semantics of pragma Inline_Only are identical to (or at -least very similar to) the GNAT implementation defined pragma -Inline_Always. You could globally replace Inline_Only with Inline_Always. - -However, to avoid that source modification, you could instead add a -configuration pragma: - -@example -pragma Rename_Pragma ( - New_Name => Inline_Only, - Renamed => Inline_Always); -@end example - -Then GNAT will treat “pragma Inline_Only …” as if you had written -“pragma Inline_Always …”. - -Pragma Inline_Only will not necessarily mean the same thing as the other Ada -compiler; it’s up to you to make sure the semantics are close enough. - -@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Rename_Pragma,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d8} -@section Pragma Restricted_Run_Time - - -Syntax: - -@example -pragma Restricted_Run_Time; -@end example - -This pragma is considered obsolescent, but is retained for -compatibility purposes. It is equivalent to: - -@example -pragma Profile (Restricted); -@end example - -which is the preferred method of setting the restricted run time -profile. - -@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{d9} -@section Pragma Restriction_Warnings - - -Syntax: - -@example -pragma Restriction_Warnings - (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); -@end example - -This pragma allows a series of restriction identifiers to be -specified (the list of allowed identifiers is the same as for -pragma @code{Restrictions}). For each of these identifiers -the compiler checks for violations of the restriction, but -generates a warning message rather than an error message -if the restriction is violated. - -One use of this is in situations where you want to know -about violations of a restriction, but you want to ignore some of -these violations. Consider this example, where you want to set -Ada_95 mode and enable style checks, but you want to know about -any other use of implementation pragmas: - -@example -pragma Restriction_Warnings (No_Implementation_Pragmas); -pragma Warnings (Off, "violation of No_Implementation_Pragmas"); -pragma Ada_95; -pragma Style_Checks ("2bfhkM160"); -pragma Warnings (On, "violation of No_Implementation_Pragmas"); -@end example - -By including the above lines in a configuration pragmas file, -the Ada_95 and Style_Checks pragmas are accepted without -generating a warning, but any other use of implementation -defined pragmas will cause a warning to be generated. - -@node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{da} -@section Pragma Reviewable - - -Syntax: - -@example -pragma Reviewable; -@end example - -This pragma is an RM-defined standard pragma, but has no effect on the -program being compiled, or on the code generated for the program. - -To obtain the required output specified in RM H.3.1, the compiler must be -run with various special switches as follows: - - -@itemize * - -@item -`Where compiler-generated run-time checks remain' - -The switch `-gnatGL' -may be used to list the expanded code in pseudo-Ada form. -Runtime checks show up in the listing either as explicit -checks or operators marked with @{@} to indicate a check is present. - -@item -`An identification of known exceptions at compile time' - -If the program is compiled with `-gnatwa', -the compiler warning messages will indicate all cases where the compiler -detects that an exception is certain to occur at run time. - -@item -`Possible reads of uninitialized variables' - -The compiler warns of many such cases, but its output is incomplete. -@end itemize - - -A supplemental static analysis tool -may be used to obtain a comprehensive list of all -possible points at which uninitialized data may be read. - - -@itemize * - -@item -`Where run-time support routines are implicitly invoked' - -In the output from `-gnatGL', -run-time calls are explicitly listed as calls to the relevant -run-time routine. - -@item -`Object code listing' - -This may be obtained either by using the `-S' switch, -or the objdump utility. - -@item -`Constructs known to be erroneous at compile time' - -These are identified by warnings issued by the compiler (use `-gnatwa'). - -@item -`Stack usage information' - -Static stack usage data (maximum per-subprogram) can be obtained via the -`-fstack-usage' switch to the compiler. -Dynamic stack usage data (per task) can be obtained via the `-u' switch -to gnatbind -@end itemize - - - -@itemize * - -@item -`Object code listing of entire partition' - -This can be obtained by compiling the partition with `-S', -or by applying objdump -to all the object files that are part of the partition. - -@item -`A description of the run-time model' - -The full sources of the run-time are available, and the documentation of -these routines describes how these run-time routines interface to the -underlying operating system facilities. - -@item -`Control and data-flow information' -@end itemize - - -A supplemental static analysis tool -may be used to obtain complete control and data-flow information, as well as -comprehensive messages identifying possible problems based on this -information. - -@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{db}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{dc} -@section Pragma Secondary_Stack_Size - - -Syntax: - -@example -pragma Secondary_Stack_Size (integer_EXPRESSION); -@end example - -This pragma appears within the task definition of a single task declaration -or a task type declaration (like pragma @code{Storage_Size}) and applies to all -task objects of that type. The argument specifies the size of the secondary -stack to be used by these task objects, and must be of an integer type. The -secondary stack is used to handle functions that return a variable-sized -result, for example a function returning an unconstrained String. - -Note this pragma only applies to targets using fixed secondary stacks, like -VxWorks 653 and bare board targets, where a fixed block for the -secondary stack is allocated from the primary stack of the task. By default, -these targets assign a percentage of the primary stack for the secondary stack, -as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, -an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. - -For most targets, the pragma does not apply as the secondary stack grows on -demand: allocated as a chain of blocks in the heap. The default size of these -blocks can be modified via the @code{-D} binder option as described in -@cite{GNAT User’s Guide}. - -Note that no check is made to see if the secondary stack can fit inside the -primary stack. - -Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} -is in effect. - -@node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{dd} -@section Pragma Share_Generic - - -Syntax: - -@example -pragma Share_Generic (GNAME @{, GNAME@}); - -GNAME ::= generic_unit_NAME | generic_instance_NAME -@end example - -This pragma is provided for compatibility with Dec Ada 83. It has -no effect in GNAT (which does not implement shared generics), other -than to check that the given names are all names of generic units or -generic instances. - -@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{de}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{df} -@section Pragma Shared - - -This pragma is provided for compatibility with Ada 83. The syntax and -semantics are identical to pragma Atomic. - -@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e0} -@section Pragma Short_Circuit_And_Or - - -Syntax: - -@example -pragma Short_Circuit_And_Or; -@end example - -This configuration pragma causes any occurrence of the AND operator applied to -operands of type Standard.Boolean to be short-circuited (i.e. the AND operator -is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This -may be useful in the context of certification protocols requiring the use of -short-circuited logical operators. If this configuration pragma occurs locally -within the file being compiled, it applies only to the file being compiled. -There is no requirement that all units in a partition use this option. - -@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e1} -@section Pragma Short_Descriptors - - -Syntax: - -@example -pragma Short_Descriptors; -@end example - -This pragma is provided for compatibility with other Ada implementations. It -is recognized but ignored by all current versions of GNAT. - -@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e2}@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e3} -@section Pragma Simple_Storage_Pool_Type - - -@geindex Storage pool -@geindex simple - -@geindex Simple storage pool - -Syntax: - -@example -pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); -@end example - -A type can be established as a ‘simple storage pool type’ by applying -the representation pragma @code{Simple_Storage_Pool_Type} to the type. -A type named in the pragma must be a library-level immutably limited record -type or limited tagged type declared immediately within a package declaration. -The type can also be a limited private type whose full type is allowed as -a simple storage pool type. - -For a simple storage pool type @code{SSP}, nonabstract primitive subprograms -@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that -are subtype conformant with the following subprogram declarations: - -@example -procedure Allocate - (Pool : in out SSP; - Storage_Address : out System.Address; - Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; - Alignment : System.Storage_Elements.Storage_Count); - -procedure Deallocate - (Pool : in out SSP; - Storage_Address : System.Address; - Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; - Alignment : System.Storage_Elements.Storage_Count); - -function Storage_Size (Pool : SSP) - return System.Storage_Elements.Storage_Count; -@end example - -Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and -@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then -applying an unchecked deallocation has no effect other than to set its actual -parameter to null. If @code{Storage_Size} is not declared, then the -@code{Storage_Size} attribute applied to an access type associated with -a pool object of type SSP returns zero. Additional operations can be declared -for a simple storage pool type (such as for supporting a mark/release -storage-management discipline). - -An object of a simple storage pool type can be associated with an access -type by specifying the attribute -@ref{e4,,Simple_Storage_Pool}. For example: - -@example -My_Pool : My_Simple_Storage_Pool_Type; - -type Acc is access My_Data_Type; - -for Acc'Simple_Storage_Pool use My_Pool; -@end example - -See attribute @ref{e4,,Simple_Storage_Pool} -for further details. - -@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e5}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e6} -@section Pragma Source_File_Name - - -Syntax: - -@example -pragma Source_File_Name ( - [Unit_Name =>] unit_NAME, - Spec_File_Name => STRING_LITERAL, - [Index => INTEGER_LITERAL]); - -pragma Source_File_Name ( - [Unit_Name =>] unit_NAME, - Body_File_Name => STRING_LITERAL, - [Index => INTEGER_LITERAL]); -@end example - -Use this to override the normal naming convention. It is a configuration -pragma, and so has the usual applicability of configuration pragmas -(i.e., it applies to either an entire partition, or to all units in a -compilation, or to a single unit, depending on how it is used). -@code{unit_name} is mapped to @code{file_name_literal}. The identifier for -the second argument is required, and indicates whether this is the file -name for the spec or for the body. - -The optional Index argument should be used when a file contains multiple -units, and when you do not want to use @code{gnatchop} to separate then -into multiple files (which is the recommended procedure to limit the -number of recompilations that are needed when some sources change). -For instance, if the source file @code{source.ada} contains - -@example -package B is -... -end B; - -with B; -procedure A is -begin - .. -end A; -@end example - -you could use the following configuration pragmas: - -@example -pragma Source_File_Name - (B, Spec_File_Name => "source.ada", Index => 1); -pragma Source_File_Name - (A, Body_File_Name => "source.ada", Index => 2); -@end example - -Note that the @code{gnatname} utility can also be used to generate those -configuration pragmas. - -Another form of the @code{Source_File_Name} pragma allows -the specification of patterns defining alternative file naming schemes -to apply to all files. - -@example -pragma Source_File_Name - ( [Spec_File_Name =>] STRING_LITERAL - [,[Casing =>] CASING_SPEC] - [,[Dot_Replacement =>] STRING_LITERAL]); - -pragma Source_File_Name - ( [Body_File_Name =>] STRING_LITERAL - [,[Casing =>] CASING_SPEC] - [,[Dot_Replacement =>] STRING_LITERAL]); - -pragma Source_File_Name - ( [Subunit_File_Name =>] STRING_LITERAL - [,[Casing =>] CASING_SPEC] - [,[Dot_Replacement =>] STRING_LITERAL]); - -CASING_SPEC ::= Lowercase | Uppercase | Mixedcase -@end example - -The first argument is a pattern that contains a single asterisk indicating -the point at which the unit name is to be inserted in the pattern string -to form the file name. The second argument is optional. If present it -specifies the casing of the unit name in the resulting file name string. -The default is lower case. Finally the third argument allows for systematic -replacement of any dots in the unit name by the specified string literal. - -Note that Source_File_Name pragmas should not be used if you are using -project files. The reason for this rule is that the project manager is not -aware of these pragmas, and so other tools that use the project file would not -be aware of the intended naming conventions. If you are using project files, -file naming is controlled by Source_File_Name_Project pragmas, which are -usually supplied automatically by the project manager. A pragma -Source_File_Name cannot appear after a @ref{e7,,Pragma Source_File_Name_Project}. - -For more details on the use of the @code{Source_File_Name} pragma, see the -sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes} -in the @cite{GNAT User’s Guide}. - -@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{e8}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{e7} -@section Pragma Source_File_Name_Project - - -This pragma has the same syntax and semantics as pragma Source_File_Name. -It is only allowed as a stand-alone configuration pragma. -It cannot appear after a @ref{e6,,Pragma Source_File_Name}, and -most importantly, once pragma Source_File_Name_Project appears, -no further Source_File_Name pragmas are allowed. - -The intention is that Source_File_Name_Project pragmas are always -generated by the Project Manager in a manner consistent with the naming -specified in a project file, and when naming is controlled in this manner, -it is not permissible to attempt to modify this naming scheme using -Source_File_Name or Source_File_Name_Project pragmas (which would not be -known to the project manager). - -@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{e9} -@section Pragma Source_Reference - - -Syntax: - -@example -pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); -@end example - -This pragma must appear as the first line of a source file. -@code{integer_literal} is the logical line number of the line following -the pragma line (for use in error messages and debugging -information). @code{string_literal} is a static string constant that -specifies the file name to be used in error messages and debugging -information. This is most notably used for the output of @code{gnatchop} -with the `-r' switch, to make sure that the original unchopped -source file is the one referred to. - -The second argument must be a string literal, it cannot be a static -string expression other than a string literal. This is because its value -is needed for error messages issued by all phases of the compiler. - -@node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{ea}@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{eb} -@section Pragma SPARK_Mode - - -Syntax: - -@example -pragma SPARK_Mode [(On | Off)] ; -@end example - -In general a program can have some parts that are in SPARK 2014 (and -follow all the rules in the SPARK Reference Manual), and some parts -that are full Ada 2012. - -The SPARK_Mode pragma is used to identify which parts are in SPARK -2014 (by default programs are in full Ada). The SPARK_Mode pragma can -be used in the following places: - - -@itemize * - -@item -As a configuration pragma, in which case it sets the default mode for -all units compiled with this pragma. - -@item -Immediately following a library-level subprogram spec - -@item -Immediately within a library-level package body - -@item -Immediately following the @code{private} keyword of a library-level -package spec - -@item -Immediately following the @code{begin} keyword of a library-level -package body - -@item -Immediately within a library-level subprogram body -@end itemize - -Normally a subprogram or package spec/body inherits the current mode -that is active at the point it is declared. But this can be overridden -by pragma within the spec or body as above. - -The basic consistency rule is that you can’t turn SPARK_Mode back -@code{On}, once you have explicitly (with a pragma) turned if -@code{Off}. So the following rules apply: - -If a subprogram spec has SPARK_Mode @code{Off}, then the body must -also have SPARK_Mode @code{Off}. - -For a package, we have four parts: - - -@itemize * - -@item -the package public declarations - -@item -the package private part - -@item -the body of the package - -@item -the elaboration code after @code{begin} -@end itemize - -For a package, the rule is that if you explicitly turn SPARK_Mode -@code{Off} for any part, then all the following parts must have -SPARK_Mode @code{Off}. Note that this may require repeating a pragma -SPARK_Mode (@code{Off}) in the body. For example, if we have a -configuration pragma SPARK_Mode (@code{On}) that turns the mode on by -default everywhere, and one particular package spec has pragma -SPARK_Mode (@code{Off}), then that pragma will need to be repeated in -the package body. - -@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{ec} -@section Pragma Static_Elaboration_Desired - - -Syntax: - -@example -pragma Static_Elaboration_Desired; -@end example - -This pragma is used to indicate that the compiler should attempt to initialize -statically the objects declared in the library unit to which the pragma applies, -when these objects are initialized (explicitly or implicitly) by an aggregate. -In the absence of this pragma, aggregates in object declarations are expanded -into assignments and loops, even when the aggregate components are static -constants. When the aggregate is present the compiler builds a static expression -that requires no run-time code, so that the initialized object can be placed in -read-only data space. If the components are not static, or the aggregate has -more that 100 components, the compiler emits a warning that the pragma cannot -be obeyed. (See also the restriction No_Implicit_Loops, which supports static -construction of larger aggregates with static components that include an others -choice.) - -@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{ed} -@section Pragma Stream_Convert - - -Syntax: - -@example -pragma Stream_Convert ( - [Entity =>] type_LOCAL_NAME, - [Read =>] function_NAME, - [Write =>] function_NAME); -@end example - -This pragma provides an efficient way of providing user-defined stream -attributes. Not only is it simpler to use than specifying the attributes -directly, but more importantly, it allows the specification to be made in such -a way that the predefined unit Ada.Streams is not loaded unless it is actually -needed (i.e. unless the stream attributes are actually used); the use of -the Stream_Convert pragma adds no overhead at all, unless the stream -attributes are actually used on the designated type. - -The first argument specifies the type for which stream functions are -provided. The second parameter provides a function used to read values -of this type. It must name a function whose argument type may be any -subtype, and whose returned type must be the type given as the first -argument to the pragma. - -The meaning of the @code{Read} parameter is that if a stream attribute directly -or indirectly specifies reading of the type given as the first parameter, -then a value of the type given as the argument to the Read function is -read from the stream, and then the Read function is used to convert this -to the required target type. - -Similarly the @code{Write} parameter specifies how to treat write attributes -that directly or indirectly apply to the type given as the first parameter. -It must have an input parameter of the type specified by the first parameter, -and the return type must be the same as the input type of the Read function. -The effect is to first call the Write function to convert to the given stream -type, and then write the result type to the stream. - -The Read and Write functions must not be overloaded subprograms. If necessary -renamings can be supplied to meet this requirement. -The usage of this attribute is best illustrated by a simple example, taken -from the GNAT implementation of package Ada.Strings.Unbounded: - -@example -function To_Unbounded (S : String) return Unbounded_String - renames To_Unbounded_String; - -pragma Stream_Convert - (Unbounded_String, To_Unbounded, To_String); -@end example - -The specifications of the referenced functions, as given in the Ada -Reference Manual are: - -@example -function To_Unbounded_String (Source : String) - return Unbounded_String; - -function To_String (Source : Unbounded_String) - return String; -@end example - -The effect is that if the value of an unbounded string is written to a stream, -then the representation of the item in the stream is in the same format that -would be used for @code{Standard.String'Output}, and this same representation -is expected when a value of this type is read from the stream. Note that the -value written always includes the bounds, even for Unbounded_String’Write, -since Unbounded_String is not an array type. - -Note that the @code{Stream_Convert} pragma is not effective in the case of -a derived type of a non-limited tagged type. If such a type is specified then -the pragma is silently ignored, and the default implementation of the stream -attributes is used instead. - -@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{ee} -@section Pragma Style_Checks - - -Syntax: - -@example -pragma Style_Checks (string_LITERAL | ALL_CHECKS | - On | Off [, LOCAL_NAME]); -@end example - -This pragma is used in conjunction with compiler switches to control the -built in style checking provided by GNAT. The compiler switches, if set, -provide an initial setting for the switches, and this pragma may be used -to modify these settings, or the settings may be provided entirely by -the use of the pragma. This pragma can be used anywhere that a pragma -is legal, including use as a configuration pragma (including use in -the @code{gnat.adc} file). - -The form with a string literal specifies which style options are to be -activated. These are additive, so they apply in addition to any previously -set style check options. The codes for the options are the same as those -used in the `-gnaty' switch to `gcc' or `gnatmake'. -For example the following two methods can be used to enable -layout checking: - - -@itemize * - -@item -@example -pragma Style_Checks ("l"); -@end example - -@item -@example -gcc -c -gnatyl ... -@end example -@end itemize - -The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent -to the use of the @code{gnaty} switch with no options. -See the @cite{GNAT User’s Guide} for details.) - -Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). -In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check -options (i.e. equivalent to @code{-gnatyg}). - -The forms with @code{Off} and @code{On} -can be used to temporarily disable style checks -as shown in the following example: - -@example -pragma Style_Checks ("k"); -- requires keywords in lower case -pragma Style_Checks (Off); -- turn off style checks -NULL; -- this will not generate an error message -pragma Style_Checks (On); -- turn style checks back on -NULL; -- this will generate an error message -@end example - -Finally the two argument form is allowed only if the first argument is -@code{On} or @code{Off}. The effect is to turn of semantic style checks -for the specified entity, as shown in the following example: - -@example -pragma Style_Checks ("r"); -- require consistency of identifier casing -Arg : Integer; -Rf1 : Integer := ARG; -- incorrect, wrong case -pragma Style_Checks (Off, Arg); -Rf2 : Integer := ARG; -- OK, no error -@end example - -@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{ef} -@section Pragma Subtitle - - -Syntax: - -@example -pragma Subtitle ([Subtitle =>] STRING_LITERAL); -@end example - -This pragma is recognized for compatibility with other Ada compilers -but is ignored by GNAT. - -@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f0} -@section Pragma Suppress - - -Syntax: - -@example -pragma Suppress (Identifier [, [On =>] Name]); -@end example - -This is a standard pragma, and supports all the check names required in -the RM. It is included here because GNAT recognizes some additional check -names that are implementation defined (as permitted by the RM): - - -@itemize * - -@item -@code{Alignment_Check} can be used to suppress alignment checks -on addresses used in address clauses. Such checks can also be suppressed -by suppressing range checks, but the specific use of @code{Alignment_Check} -allows suppression of alignment checks without suppressing other range checks. -Note that @code{Alignment_Check} is suppressed by default on machines (such as -the x86) with non-strict alignment. - -@item -@code{Atomic_Synchronization} can be used to suppress the special memory -synchronization instructions that are normally generated for access to -@code{Atomic} variables to ensure correct synchronization between tasks -that use such variables for synchronization purposes. - -@item -@code{Duplicated_Tag_Check} Can be used to suppress the check that is generated -for a duplicated tag value when a tagged type is declared. - -@item -@code{Container_Checks} Can be used to suppress all checks within Ada.Containers -and instances of its children, including Tampering_Check. - -@item -@code{Tampering_Check} Can be used to suppress tampering check in the containers. - -@item -@code{Predicate_Check} can be used to control whether predicate checks are -active. It is applicable only to predicates for which the policy is -@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given -predicate is ignored or checked for the whole program, the use of -@code{Suppress} and @code{Unsuppress} with this check name allows a given -predicate to be turned on and off at specific points in the program. - -@item -@code{Validity_Check} can be used specifically to control validity checks. -If @code{Suppress} is used to suppress validity checks, then no validity -checks are performed, including those specified by the appropriate compiler -switch or the @code{Validity_Checks} pragma. - -@item -Additional check names previously introduced by use of the @code{Check_Name} -pragma are also allowed. -@end itemize - -Note that pragma Suppress gives the compiler permission to omit -checks, but does not require the compiler to omit checks. The compiler -will generate checks if they are essentially free, even when they are -suppressed. In particular, if the compiler can prove that a certain -check will necessarily fail, it will generate code to do an -unconditional ‘raise’, even if checks are suppressed. The compiler -warns in this case. - -Of course, run-time checks are omitted whenever the compiler can prove -that they will not fail, whether or not checks are suppressed. - -@node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f1} -@section Pragma Suppress_All - - -Syntax: - -@example -pragma Suppress_All; -@end example - -This pragma can appear anywhere within a unit. -The effect is to apply @code{Suppress (All_Checks)} to the unit -in which it appears. This pragma is implemented for compatibility with DEC -Ada 83 usage where it appears at the end of a unit, and for compatibility -with Rational Ada, where it appears as a program unit pragma. -The use of the standard Ada pragma @code{Suppress (All_Checks)} -as a normal configuration pragma is the preferred usage in GNAT. - -@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f2}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f3} -@section Pragma Suppress_Debug_Info - - -Syntax: - -@example -pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); -@end example - -This pragma can be used to suppress generation of debug information -for the specified entity. It is intended primarily for use in debugging -the debugger, and navigating around debugger problems. - -@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f4} -@section Pragma Suppress_Exception_Locations - - -Syntax: - -@example -pragma Suppress_Exception_Locations; -@end example - -In normal mode, a raise statement for an exception by default generates -an exception message giving the file name and line number for the location -of the raise. This is useful for debugging and logging purposes, but this -entails extra space for the strings for the messages. The configuration -pragma @code{Suppress_Exception_Locations} can be used to suppress the -generation of these strings, with the result that space is saved, but the -exception message for such raises is null. This configuration pragma may -appear in a global configuration pragma file, or in a specific unit as -usual. It is not required that this pragma be used consistently within -a partition, so it is fine to have some units within a partition compiled -with this pragma and others compiled in normal mode without it. - -@node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{f5}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f6} -@section Pragma Suppress_Initialization - - -@geindex Suppressing initialization - -@geindex Initialization -@geindex suppression of - -Syntax: - -@example -pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); -@end example - -Here variable_or_subtype_Name is the name introduced by a type declaration -or subtype declaration or the name of a variable introduced by an -object declaration. - -In the case of a type or subtype -this pragma suppresses any implicit or explicit initialization -for all variables of the given type or subtype, -including initialization resulting from the use of pragmas -Normalize_Scalars or Initialize_Scalars. - -This is considered a representation item, so it cannot be given after -the type is frozen. It applies to all subsequent object declarations, -and also any allocator that creates objects of the type. - -If the pragma is given for the first subtype, then it is considered -to apply to the base type and all its subtypes. If the pragma is given -for other than a first subtype, then it applies only to the given subtype. -The pragma may not be given after the type is frozen. - -Note that this includes eliminating initialization of discriminants -for discriminated types, and tags for tagged types. In these cases, -you will have to use some non-portable mechanism (e.g. address -overlays or unchecked conversion) to achieve required initialization -of these fields before accessing any object of the corresponding type. - -For the variable case, implicit initialization for the named variable -is suppressed, just as though its subtype had been given in a pragma -Suppress_Initialization, as described above. - -@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{f7} -@section Pragma Task_Name - - -Syntax - -@example -pragma Task_Name (string_EXPRESSION); -@end example - -This pragma appears within a task definition (like pragma -@code{Priority}) and applies to the task in which it appears. The -argument must be of type String, and provides a name to be used for -the task instance when the task is created. Note that this expression -is not required to be static, and in particular, it can contain -references to task discriminants. This facility can be used to -provide different names for different tasks as they are created, -as illustrated in the example below. - -The task name is recorded internally in the run-time structures -and is accessible to tools like the debugger. In addition the -routine @code{Ada.Task_Identification.Image} will return this -string, with a unique task address appended. - -@example --- Example of the use of pragma Task_Name - -with Ada.Task_Identification; -use Ada.Task_Identification; -with Text_IO; use Text_IO; -procedure t3 is - - type Astring is access String; - - task type Task_Typ (Name : access String) is - pragma Task_Name (Name.all); - end Task_Typ; - - task body Task_Typ is - Nam : constant String := Image (Current_Task); - begin - Put_Line ("-->" & Nam (1 .. 14) & "<--"); - end Task_Typ; - - type Ptr_Task is access Task_Typ; - Task_Var : Ptr_Task; - -begin - Task_Var := - new Task_Typ (new String'("This is task 1")); - Task_Var := - new Task_Typ (new String'("This is task 2")); -end; -@end example - -@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{f8} -@section Pragma Task_Storage - - -Syntax: - -@example -pragma Task_Storage ( - [Task_Type =>] LOCAL_NAME, - [Top_Guard =>] static_integer_EXPRESSION); -@end example - -This pragma specifies the length of the guard area for tasks. The guard -area is an additional storage area allocated to a task. A value of zero -means that either no guard area is created or a minimal guard area is -created, depending on the target. This pragma can appear anywhere a -@code{Storage_Size} attribute definition clause is allowed for a task -type. - -@node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{f9}@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fa} -@section Pragma Test_Case - - -@geindex Test cases - -Syntax: - -@example -pragma Test_Case ( - [Name =>] static_string_Expression - ,[Mode =>] (Nominal | Robustness) - [, Requires => Boolean_Expression] - [, Ensures => Boolean_Expression]); -@end example - -The @code{Test_Case} pragma allows defining fine-grain specifications -for use by testing tools. -The compiler checks the validity of the @code{Test_Case} pragma, but its -presence does not lead to any modification of the code generated by the -compiler. - -@code{Test_Case} pragmas may only appear immediately following the -(separate) declaration of a subprogram in a package declaration, inside -a package spec unit. Only other pragmas may intervene (that is appear -between the subprogram declaration and a test case). - -The compiler checks that boolean expressions given in @code{Requires} and -@code{Ensures} are valid, where the rules for @code{Requires} are the -same as the rule for an expression in @code{Precondition} and the rules -for @code{Ensures} are the same as the rule for an expression in -@code{Postcondition}. In particular, attributes @code{'Old} and -@code{'Result} can only be used within the @code{Ensures} -expression. The following is an example of use within a package spec: - -@example -package Math_Functions is - ... - function Sqrt (Arg : Float) return Float; - pragma Test_Case (Name => "Test 1", - Mode => Nominal, - Requires => Arg < 10000.0, - Ensures => Sqrt'Result < 10.0); - ... -end Math_Functions; -@end example - -The meaning of a test case is that there is at least one context where -@code{Requires} holds such that, if the associated subprogram is executed in -that context, then @code{Ensures} holds when the subprogram returns. -Mode @code{Nominal} indicates that the input context should also satisfy the -precondition of the subprogram, and the output context should also satisfy its -postcondition. Mode @code{Robustness} indicates that the precondition and -postcondition of the subprogram should be ignored for this test case. - -@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{fb}@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fc} -@section Pragma Thread_Local_Storage - - -@geindex Task specific storage - -@geindex TLS (Thread Local Storage) - -@geindex Task_Attributes - -Syntax: - -@example -pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); -@end example - -This pragma specifies that the specified entity, which must be -a variable declared in a library-level package, is to be marked as -“Thread Local Storage” (@code{TLS}). On systems supporting this (which -include Windows, Solaris, GNU/Linux, and VxWorks), this causes each -thread (and hence each Ada task) to see a distinct copy of the variable. - -The variable must not have default initialization, and if there is -an explicit initialization, it must be either @code{null} for an -access variable, a static expression for a scalar variable, or a fully -static aggregate for a composite type, that is to say, an aggregate all -of whose components are static, and which does not include packed or -discriminated components. - -This provides a low-level mechanism similar to that provided by -the @code{Ada.Task_Attributes} package, but much more efficient -and is also useful in writing interface code that will interact -with foreign threads. - -If this pragma is used on a system where @code{TLS} is not supported, -then an error message will be generated and the program will be rejected. - -@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{fd} -@section Pragma Time_Slice - - -Syntax: - -@example -pragma Time_Slice (static_duration_EXPRESSION); -@end example - -For implementations of GNAT on operating systems where it is possible -to supply a time slice value, this pragma may be used for this purpose. -It is ignored if it is used in a system that does not allow this control, -or if it appears in other than the main program unit. - -@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{fe} -@section Pragma Title - - -Syntax: - -@example -pragma Title (TITLING_OPTION [, TITLING OPTION]); - -TITLING_OPTION ::= - [Title =>] STRING_LITERAL, -| [Subtitle =>] STRING_LITERAL -@end example - -Syntax checked but otherwise ignored by GNAT. This is a listing control -pragma used in DEC Ada 83 implementations to provide a title and/or -subtitle for the program listing. The program listing generated by GNAT -does not have titles or subtitles. - -Unlike other pragmas, the full flexibility of named notation is allowed -for this pragma, i.e., the parameters may be given in any order if named -notation is used, and named and positional notation can be mixed -following the normal rules for procedure calls in Ada. - -@node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{ff} -@section Pragma Type_Invariant - - -Syntax: - -@example -pragma Type_Invariant - ([Entity =>] type_LOCAL_NAME, - [Check =>] EXPRESSION); -@end example - -The @code{Type_Invariant} pragma is intended to be an exact -replacement for the language-defined @code{Type_Invariant} -aspect, and shares its restrictions and semantics. It differs -from the language defined @code{Invariant} pragma in that it -does not permit a string parameter, and it is -controlled by the assertion identifier @code{Type_Invariant} -rather than @code{Invariant}. - -@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{100}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{101} -@section Pragma Type_Invariant_Class - - -Syntax: - -@example -pragma Type_Invariant_Class - ([Entity =>] type_LOCAL_NAME, - [Check =>] EXPRESSION); -@end example - -The @code{Type_Invariant_Class} pragma is intended to be an exact -replacement for the language-defined @code{Type_Invariant'Class} -aspect, and shares its restrictions and semantics. - -Note: This pragma is called @code{Type_Invariant_Class} rather than -@code{Type_Invariant'Class} because the latter would not be strictly -conforming to the allowed syntax for pragmas. The motivation -for providing pragmas equivalent to the aspects is to allow a program -to be written using the pragmas, and then compiled if necessary -using an Ada compiler that does not recognize the pragmas or -aspects, but is prepared to ignore the pragmas. The assertion -policy that controls this pragma is @code{Type_Invariant'Class}, -not @code{Type_Invariant_Class}. - -@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{102} -@section Pragma Unchecked_Union - - -@geindex Unions in C - -Syntax: - -@example -pragma Unchecked_Union (first_subtype_LOCAL_NAME); -@end example - -This pragma is used to specify a representation of a record type that is -equivalent to a C union. It was introduced as a GNAT implementation defined -pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this -pragma, making it language defined, and GNAT fully implements this extended -version in all language modes (Ada 83, Ada 95, and Ada 2005). For full -details, consult the Ada 2012 Reference Manual, section B.3.3. - -@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{103} -@section Pragma Unevaluated_Use_Of_Old - - -@geindex Attribute Old - -@geindex Attribute Loop_Entry - -@geindex Unevaluated_Use_Of_Old - -Syntax: - -@example -pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); -@end example - -This pragma controls the processing of attributes Old and Loop_Entry. -If either of these attributes is used in a potentially unevaluated -expression (e.g. the then or else parts of an if expression), then -normally this usage is considered illegal if the prefix of the attribute -is other than an entity name. The language requires this -behavior for Old, and GNAT copies the same rule for Loop_Entry. - -The reason for this rule is that otherwise, we can have a situation -where we save the Old value, and this results in an exception, even -though we might not evaluate the attribute. Consider this example: - -@example -package UnevalOld is - K : Character; - procedure U (A : String; C : Boolean) -- ERROR - with Post => (if C then A(1)'Old = K else True); -end; -@end example - -If procedure U is called with a string with a lower bound of 2, and -C false, then an exception would be raised trying to evaluate A(1) -on entry even though the value would not be actually used. - -Although the rule guarantees against this possibility, it is sometimes -too restrictive. For example if we know that the string has a lower -bound of 1, then we will never raise an exception. -The pragma @code{Unevaluated_Use_Of_Old} can be -used to modify this behavior. If the argument is @code{Error} then an -error is given (this is the default RM behavior). If the argument is -@code{Warn} then the usage is allowed as legal but with a warning -that an exception might be raised. If the argument is @code{Allow} -then the usage is allowed as legal without generating a warning. - -This pragma may appear as a configuration pragma, or in a declarative -part or package specification. In the latter case it applies to -uses up to the end of the corresponding statement sequence or -sequence of package declarations. - -@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{104} -@section Pragma Unimplemented_Unit - - -Syntax: - -@example -pragma Unimplemented_Unit; -@end example - -If this pragma occurs in a unit that is processed by the compiler, GNAT -aborts with the message @code{xxx not implemented}, where -@code{xxx} is the name of the current compilation unit. This pragma is -intended to allow the compiler to handle unimplemented library units in -a clean manner. - -The abort only happens if code is being generated. Thus you can use -specs of unimplemented packages in syntax or semantic checking mode. - -@node Pragma Universal_Aliasing,Pragma Unmodified,Pragma Unimplemented_Unit,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{105}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{106} -@section Pragma Universal_Aliasing - - -Syntax: - -@example -pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; -@end example - -@code{type_LOCAL_NAME} must refer to a type declaration in the current -declarative part. The effect is to inhibit strict type-based aliasing -optimization for the given type. In other words, the effect is as though -access types designating this type were subject to pragma No_Strict_Aliasing. -For a detailed description of the strict aliasing optimization, and the -situations in which it must be suppressed, see the section on -@code{Optimization and Strict Aliasing} in the @cite{GNAT User’s Guide}. - -@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Aliasing,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{107}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{108} -@section Pragma Unmodified - - -@geindex Warnings -@geindex unmodified - -Syntax: - -@example -pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); -@end example - -This pragma signals that the assignable entities (variables, -@code{out} parameters, @code{in out} parameters) whose names are listed are -deliberately not assigned in the current source unit. This -suppresses warnings about the -entities being referenced but not assigned, and in addition a warning will be -generated if one of these entities is in fact assigned in the -same unit as the pragma (or in the corresponding body, or one -of its subunits). - -This is particularly useful for clearly signaling that a particular -parameter is not modified, even though the spec suggests that it might -be. - -For the variable case, warnings are never given for unreferenced variables -whose name contains one of the substrings -@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSE, TMP, TEMP} in any casing. Such names -are typically to be used in cases where such warnings are expected. -Thus it is never necessary to use @code{pragma Unmodified} for such -variables, though it is harmless to do so. - -@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{109}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10a} -@section Pragma Unreferenced - - -@geindex Warnings -@geindex unreferenced - -Syntax: - -@example -pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); -pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); -@end example - -This pragma signals that the entities whose names are listed are -deliberately not referenced in the current source unit after the -occurrence of the pragma. This -suppresses warnings about the -entities being unreferenced, and in addition a warning will be -generated if one of these entities is in fact subsequently referenced in the -same unit as the pragma (or in the corresponding body, or one -of its subunits). - -This is particularly useful for clearly signaling that a particular -parameter is not referenced in some particular subprogram implementation -and that this is deliberate. It can also be useful in the case of -objects declared only for their initialization or finalization side -effects. - -If @code{LOCAL_NAME} identifies more than one matching homonym in the -current scope, then the entity most recently declared is the one to which -the pragma applies. Note that in the case of accept formals, the pragma -Unreferenced may appear immediately after the keyword @code{do} which -allows the indication of whether or not accept formals are referenced -or not to be given individually for each accept statement. - -The left hand side of an assignment does not count as a reference for the -purpose of this pragma. Thus it is fine to assign to an entity for which -pragma Unreferenced is given. However, use of an entity as an actual for -an out parameter does count as a reference unless warnings for unread output -parameters are enabled via @code{-gnatw.o}. - -Note that if a warning is desired for all calls to a given subprogram, -regardless of whether they occur in the same unit as the subprogram -declaration, then this pragma should not be used (calls from another -unit would not be flagged); pragma Obsolescent can be used instead -for this purpose, see @ref{ac,,Pragma Obsolescent}. - -The second form of pragma @code{Unreferenced} is used within a context -clause. In this case the arguments must be unit names of units previously -mentioned in @code{with} clauses (similar to the usage of pragma -@code{Elaborate_All}). The effect is to suppress warnings about unreferenced -units and unreferenced entities within these units. - -For the variable case, warnings are never given for unreferenced variables -whose name contains one of the substrings -@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names -are typically to be used in cases where such warnings are expected. -Thus it is never necessary to use @code{pragma Unreferenced} for such -variables, though it is harmless to do so. - -@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10b}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10c} -@section Pragma Unreferenced_Objects - - -@geindex Warnings -@geindex unreferenced - -Syntax: - -@example -pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); -@end example - -This pragma signals that for the types or subtypes whose names are -listed, objects which are declared with one of these types or subtypes may -not be referenced, and if no references appear, no warnings are given. - -This is particularly useful for objects which are declared solely for their -initialization and finalization effect. Such variables are sometimes referred -to as RAII variables (Resource Acquisition Is Initialization). Using this -pragma on the relevant type (most typically a limited controlled type), the -compiler will automatically suppress unwanted warnings about these variables -not being referenced. - -@node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{10d} -@section Pragma Unreserve_All_Interrupts - - -Syntax: - -@example -pragma Unreserve_All_Interrupts; -@end example - -Normally certain interrupts are reserved to the implementation. Any attempt -to attach an interrupt causes Program_Error to be raised, as described in -RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in -many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is -reserved to the implementation, so that @code{Ctrl-C} can be used to -interrupt execution. - -If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in -a program, then all such interrupts are unreserved. This allows the -program to handle these interrupts, but disables their standard -functions. For example, if this pragma is used, then pressing -@code{Ctrl-C} will not automatically interrupt execution. However, -a program can then handle the @code{SIGINT} interrupt as it chooses. - -For a full list of the interrupts handled in a specific implementation, -see the source code for the spec of @code{Ada.Interrupts.Names} in -file @code{a-intnam.ads}. This is a target dependent file that contains the -list of interrupts recognized for a given target. The documentation in -this file also specifies what interrupts are affected by the use of -the @code{Unreserve_All_Interrupts} pragma. - -For a more general facility for controlling what interrupts can be -handled, see pragma @code{Interrupt_State}, which subsumes the functionality -of the @code{Unreserve_All_Interrupts} pragma. - -@node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{10e} -@section Pragma Unsuppress - - -Syntax: - -@example -pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); -@end example - -This pragma undoes the effect of a previous pragma @code{Suppress}. If -there is no corresponding pragma @code{Suppress} in effect, it has no -effect. The range of the effect is the same as for pragma -@code{Suppress}. The meaning of the arguments is identical to that used -in pragma @code{Suppress}. - -One important application is to ensure that checks are on in cases where -code depends on the checks for its correct functioning, so that the code -will compile correctly even if the compiler switches are set to suppress -checks. For example, in a program that depends on external names of tagged -types and wants to ensure that the duplicated tag check occurs even if all -run-time checks are suppressed by a compiler switch, the following -configuration pragma will ensure this test is not suppressed: - -@example -pragma Unsuppress (Duplicated_Tag_Check); -@end example - -This pragma is standard in Ada 2005. It is available in all earlier versions -of Ada as an implementation-defined pragma. - -Note that in addition to the checks defined in the Ada RM, GNAT recognizes a -number of implementation-defined check names. See the description of pragma -@code{Suppress} for full details. - -@node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{10f} -@section Pragma Use_VADS_Size - - -@geindex Size -@geindex VADS compatibility - -@geindex Rational profile - -Syntax: - -@example -pragma Use_VADS_Size; -@end example - -This is a configuration pragma. In a unit to which it applies, any use -of the ‘Size attribute is automatically interpreted as a use of the -‘VADS_Size attribute. Note that this may result in incorrect semantic -processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in -the handling of existing code which depends on the interpretation of Size -as implemented in the VADS compiler. See description of the VADS_Size -attribute for further details. - -@node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{110}@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{111} -@section Pragma Unused - - -@geindex Warnings -@geindex unused - -Syntax: - -@example -pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); -@end example - -This pragma signals that the assignable entities (variables, -@code{out} parameters, and @code{in out} parameters) whose names are listed -deliberately do not get assigned or referenced in the current source unit -after the occurrence of the pragma in the current source unit. This -suppresses warnings about the entities that are unreferenced and/or not -assigned, and, in addition, a warning will be generated if one of these -entities gets assigned or subsequently referenced in the same unit as the -pragma (in the corresponding body or one of its subunits). - -This is particularly useful for clearly signaling that a particular -parameter is not modified or referenced, even though the spec suggests -that it might be. - -For the variable case, warnings are never given for unreferenced -variables whose name contains one of the substrings -@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names -are typically to be used in cases where such warnings are expected. -Thus it is never necessary to use @code{pragma Unused} for such -variables, though it is harmless to do so. - -@node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{112} -@section Pragma Validity_Checks - - -Syntax: - -@example -pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); -@end example - -This pragma is used in conjunction with compiler switches to control the -built-in validity checking provided by GNAT. The compiler switches, if set -provide an initial setting for the switches, and this pragma may be used -to modify these settings, or the settings may be provided entirely by -the use of the pragma. This pragma can be used anywhere that a pragma -is legal, including use as a configuration pragma (including use in -the @code{gnat.adc} file). - -The form with a string literal specifies which validity options are to be -activated. The validity checks are first set to include only the default -reference manual settings, and then a string of letters in the string -specifies the exact set of options required. The form of this string -is exactly as described for the `-gnatVx' compiler switch (see the -GNAT User’s Guide for details). For example the following two -methods can be used to enable validity checking for mode @code{in} and -@code{in out} subprogram parameters: - - -@itemize * - -@item -@example -pragma Validity_Checks ("im"); -@end example - -@item -@example -$ gcc -c -gnatVim ... -@end example -@end itemize - -The form ALL_CHECKS activates all standard checks (its use is equivalent -to the use of the @code{gnatVa} switch). - -The forms with @code{Off} and @code{On} can be used to temporarily disable -validity checks as shown in the following example: - -@example -pragma Validity_Checks ("c"); -- validity checks for copies -pragma Validity_Checks (Off); -- turn off validity checks -A := B; -- B will not be validity checked -pragma Validity_Checks (On); -- turn validity checks back on -A := C; -- C will be validity checked -@end example - -@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{113}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{114} -@section Pragma Volatile - - -Syntax: - -@example -pragma Volatile (LOCAL_NAME); -@end example - -This pragma is defined by the Ada Reference Manual, and the GNAT -implementation is fully conformant with this definition. The reason it -is mentioned in this section is that a pragma of the same name was supplied -in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 -implementation of pragma Volatile is upwards compatible with the -implementation in DEC Ada 83. - -@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{115}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{116} -@section Pragma Volatile_Full_Access - - -Syntax: - -@example -pragma Volatile_Full_Access (LOCAL_NAME); -@end example - -This is similar in effect to pragma Volatile, except that any reference to the -object is guaranteed to be done only with instructions that read or write all -the bits of the object. Furthermore, if the object is of a composite type, -then any reference to a subcomponent of the object is guaranteed to read -and/or write all the bits of the object. - -The intention is that this be suitable for use with memory-mapped I/O devices -on some machines. Note that there are two important respects in which this is -different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} -object is not a sequential action in the RM 9.10 sense and, therefore, does -not create a synchronization point. Second, in the case of @code{pragma Atomic}, -there is no guarantee that all the bits will be accessed if the reference -is not to the whole object; the compiler is allowed (and generally will) -access only part of the object in this case. - -@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{117}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{118} -@section Pragma Volatile_Function - - -Syntax: - -@example -pragma Volatile_Function [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} -in the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{119} -@section Pragma Warning_As_Error - - -Syntax: - -@example -pragma Warning_As_Error (static_string_EXPRESSION); -@end example - -This configuration pragma allows the programmer to specify a set -of warnings that will be treated as errors. Any warning that -matches the pattern given by the pragma argument will be treated -as an error. This gives more precise control than -gnatwe, -which treats warnings as errors. - -This pragma can apply to regular warnings (messages enabled by -gnatw) -and to style warnings (messages that start with “(style)”, -enabled by -gnaty). - -The pattern may contain asterisks, which match zero or more characters -in the message. For example, you can use @code{pragma Warning_As_Error -("bits of*unused")} to treat the warning message @code{warning: 960 bits of -"a" unused} as an error. All characters other than asterisk are treated -as literal characters in the match. The match is case insensitive; for -example XYZ matches xyz. - -Note that the pattern matches if it occurs anywhere within the warning -message string (it is not necessary to put an asterisk at the start and -the end of the message, since this is implied). - -Another possibility for the static_string_EXPRESSION which works whether -or not error tags are enabled (`-gnatw.d') is to use a single -`-gnatw' tag string, enclosed in brackets, -as shown in the example below, to treat one category of warnings as errors. -Note that if you want to treat multiple categories of warnings as errors, -you can use multiple pragma Warning_As_Error. - -The above use of patterns to match the message applies only to warning -messages generated by the front end. This pragma can also be applied to -warnings provided by the back end and mentioned in @ref{11a,,Pragma Warnings}. -By using a single full `-Wxxx' switch in the pragma, such warnings -can also be treated as errors. - -The pragma can appear either in a global configuration pragma file -(e.g. @code{gnat.adc}), or at the start of a file. Given a global -configuration pragma file containing: - -@example -pragma Warning_As_Error ("[-gnatwj]"); -@end example - -which will treat all obsolescent feature warnings as errors, the -following program compiles as shown (compile options here are -`-gnatwa.d -gnatl -gnatj55'). - -@example - 1. pragma Warning_As_Error ("*never assigned*"); - 2. function Warnerr return String is - 3. X : Integer; - | - >>> error: variable "X" is never read and - never assigned [-gnatwv] [warning-as-error] - - 4. Y : Integer; - | - >>> warning: variable "Y" is assigned but - never read [-gnatwu] - - 5. begin - 6. Y := 0; - 7. return %ABC%; - | - >>> error: use of "%" is an obsolescent - feature (RM J.2(4)), use """ instead - [-gnatwj] [warning-as-error] - - 8. end; - -8 lines: No errors, 3 warnings (2 treated as errors) -@end example - -Note that this pragma does not affect the set of warnings issued in -any way, it merely changes the effect of a matching warning if one -is produced as a result of other warnings options. As shown in this -example, if the pragma results in a warning being treated as an error, -the tag is changed from “warning:” to “error:” and the string -“[warning-as-error]” is appended to the end of the message. - -@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11b}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11a} -@section Pragma Warnings - - -Syntax: - -@example -pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); - -DETAILS ::= On | Off -DETAILS ::= On | Off, local_NAME -DETAILS ::= static_string_EXPRESSION -DETAILS ::= On | Off, static_string_EXPRESSION - -TOOL_NAME ::= GNAT | GNATprove - -REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} -@end example - -Note: in Ada 83 mode, a string literal may be used in place of a static string -expression (which does not exist in Ada 83). - -Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the -second form is always understood. If the intention is to use -the fourth form, then you can write @code{NAME & ""} to force the -interpretation as a `static_string_EXPRESSION'. - -Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted -that way. The use of the @code{TOOL_NAME} argument is relevant only to users -of SPARK and GNATprove, see last part of this section for details. - -Normally warnings are enabled, with the output being controlled by -the command line switch. Warnings (@code{Off}) turns off generation of -warnings until a Warnings (@code{On}) is encountered or the end of the -current unit. If generation of warnings is turned off using this -pragma, then some or all of the warning messages are suppressed, -regardless of the setting of the command line switches. - -The @code{Reason} parameter may optionally appear as the last argument -in any of the forms of this pragma. It is intended purely for the -purposes of documenting the reason for the @code{Warnings} pragma. -The compiler will check that the argument is a static string but -otherwise ignore this argument. Other tools may provide specialized -processing for this string. - -The form with a single argument (or two arguments if Reason present), -where the first argument is @code{ON} or @code{OFF} -may be used as a configuration pragma. - -If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for -the specified entity. This suppression is effective from the point where -it occurs till the end of the extended scope of the variable (similar to -the scope of @code{Suppress}). This form cannot be used as a configuration -pragma. - -In the case where the first argument is other than @code{ON} or -@code{OFF}, -the third form with a single static_string_EXPRESSION argument (and possible -reason) provides more precise -control over which warnings are active. The string is a list of letters -specifying which warnings are to be activated and which deactivated. The -code for these letters is the same as the string used in the command -line switch controlling warnings. For a brief summary, use the gnatmake -command with no arguments, which will generate usage information containing -the list of warnings switches supported. For -full details see the section on @code{Warning Message Control} in the -@cite{GNAT User’s Guide}. -This form can also be used as a configuration pragma. - -The warnings controlled by the @code{-gnatw} switch are generated by the -front end of the compiler. The GCC back end can provide additional warnings -and they are controlled by the @code{-W} switch. Such warnings can be -identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the -message which designates the @code{-W`xxx'} switch that controls the message. -The form with a single `static_string_EXPRESSION' argument also works for these -warnings, but the string must be a single full @code{-W`xxx'} switch in this -case. The above reference lists a few examples of these additional warnings. - -The specified warnings will be in effect until the end of the program -or another pragma @code{Warnings} is encountered. The effect of the pragma is -cumulative. Initially the set of warnings is the standard default set -as possibly modified by compiler switches. Then each pragma Warning -modifies this set of warnings as specified. This form of the pragma may -also be used as a configuration pragma. - -The fourth form, with an @code{On|Off} parameter and a string, is used to -control individual messages, based on their text. The string argument -is a pattern that is used to match against the text of individual -warning messages (not including the initial “warning: “ tag). - -The pattern may contain asterisks, which match zero or more characters in -the message. For example, you can use -@code{pragma Warnings (Off, "bits of*unused")} to suppress the warning -message @code{warning: 960 bits of "a" unused}. No other regular -expression notations are permitted. All characters other than asterisk in -these three specific cases are treated as literal characters in the match. -The match is case insensitive, for example XYZ matches xyz. - -Note that the pattern matches if it occurs anywhere within the warning -message string (it is not necessary to put an asterisk at the start and -the end of the message, since this is implied). - -The above use of patterns to match the message applies only to warning -messages generated by the front end. This form of the pragma with a string -argument can also be used to control warnings provided by the back end and -mentioned above. By using a single full @code{-W`xxx'} switch in the pragma, -such warnings can be turned on and off. - -There are two ways to use the pragma in this form. The OFF form can be used -as a configuration pragma. The effect is to suppress all warnings (if any) -that match the pattern string throughout the compilation (or match the --W switch in the back end case). - -The second usage is to suppress a warning locally, and in this case, two -pragmas must appear in sequence: - -@example -pragma Warnings (Off, Pattern); -... code where given warning is to be suppressed -pragma Warnings (On, Pattern); -@end example - -In this usage, the pattern string must match in the Off and On -pragmas, and (if `-gnatw.w' is given) at least one matching -warning must be suppressed. - -Note: if the ON form is not found, then the effect of the OFF form extends -until the end of the file (pragma Warnings is purely textual, so its effect -does not stop at the end of the enclosing scope). - -Note: to write a string that will match any warning, use the string -@code{"***"}. It will not work to use a single asterisk or two -asterisks since this looks like an operator name. This form with three -asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching -@code{pragma Warnings (On, "***")} will be required. This can be -helpful in avoiding forgetting to turn warnings back on. - -Note: the debug flag @code{-gnatd.i} can be -used to cause the compiler to entirely ignore all WARNINGS pragmas. This can -be useful in checking whether obsolete pragmas in existing programs are hiding -real problems. - -Note: pragma Warnings does not affect the processing of style messages. See -separate entry for pragma Style_Checks for control of style messages. - -Users of the formal verification tool GNATprove for the SPARK subset of Ada may -use the version of the pragma with a @code{TOOL_NAME} parameter. - -If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the -compiler or @code{GNATprove} for the formal verification tool. A given tool only -takes into account pragma Warnings that do not specify a tool name, or that -specify the matching tool name. This makes it possible to disable warnings -selectively for each tool, and as a consequence to detect useless pragma -Warnings with switch @code{-gnatw.w}. - -@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{11c} -@section Pragma Weak_External - - -Syntax: - -@example -pragma Weak_External ([Entity =>] LOCAL_NAME); -@end example - -@code{LOCAL_NAME} must refer to an object that is declared at the library -level. This pragma specifies that the given entity should be marked as a -weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} -in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead -of a regular symbol, that is to say a symbol that does not have to be -resolved by the linker if used in conjunction with a pragma Import. - -When a weak symbol is not resolved by the linker, its address is set to -zero. This is useful in writing interfaces to external modules that may -or may not be linked in the final executable, for example depending on -configuration settings. - -If a program references at run time an entity to which this pragma has been -applied, and the corresponding symbol was not resolved at link time, then -the execution of the program is erroneous. It is not erroneous to take the -Address of such an entity, for example to guard potential references, -as shown in the example below. - -Some file formats do not support weak symbols so not all target machines -support this pragma. - -@example --- Example of the use of pragma Weak_External - -package External_Module is - key : Integer; - pragma Import (C, key); - pragma Weak_External (key); - function Present return boolean; -end External_Module; - -with System; use System; -package body External_Module is - function Present return boolean is - begin - return key'Address /= System.Null_Address; - end Present; -end External_Module; -@end example - -@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{11d} -@section Pragma Wide_Character_Encoding - - -Syntax: - -@example -pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); -@end example - -This pragma specifies the wide character encoding to be used in program -source text appearing subsequently. It is a configuration pragma, but may -also be used at any point that a pragma is allowed, and it is permissible -to have more than one such pragma in a file, allowing multiple encodings -to appear within the same file. - -However, note that the pragma cannot immediately precede the relevant -wide character, because then the previous encoding will still be in -effect, causing “illegal character” errors. - -The argument can be an identifier or a character literal. In the identifier -case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, -@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal -case it is correspondingly one of the characters @code{h}, @code{u}, -@code{s}, @code{e}, @code{8}, or @code{b}. - -Note that when the pragma is used within a file, it affects only the -encoding within that file, and does not affect withed units, specs, -or subunits. - -@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top -@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{11e}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{11f}@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{120} -@chapter Implementation Defined Aspects - - -Ada defines (throughout the Ada 2012 reference manual, summarized -in Annex K) a set of aspects that can be specified for certain entities. -These language defined aspects are implemented in GNAT in Ada 2012 mode -and work as described in the Ada 2012 Reference Manual. - -In addition, Ada 2012 allows implementations to define additional aspects -whose meaning is defined by the implementation. GNAT provides -a number of these implementation-defined aspects which can be used -to extend and enhance the functionality of the compiler. This section of -the GNAT reference manual describes these additional aspects. - -Note that any program using these aspects may not be portable to -other compilers (although GNAT implements this set of aspects on all -platforms). Therefore if portability to other compilers is an important -consideration, you should minimize the use of these aspects. - -Note that for many of these aspects, the effect is essentially similar -to the use of a pragma or attribute specification with the same name -applied to the entity. For example, if we write: - -@example -type R is range 1 .. 100 - with Value_Size => 10; -@end example - -then the effect is the same as: - -@example -type R is range 1 .. 100; -for R'Value_Size use 10; -@end example - -and if we write: - -@example -type R is new Integer - with Shared => True; -@end example - -then the effect is the same as: - -@example -type R is new Integer; -pragma Shared (R); -@end example - -In the documentation below, such cases are simply marked -as being boolean aspects equivalent to the corresponding pragma -or attribute definition clause. - -@menu -* Aspect Abstract_State:: -* Aspect Annotate:: -* Aspect Async_Readers:: -* Aspect Async_Writers:: -* Aspect Constant_After_Elaboration:: -* Aspect Contract_Cases:: -* Aspect Depends:: -* Aspect Default_Initial_Condition:: -* Aspect Dimension:: -* Aspect Dimension_System:: -* Aspect Disable_Controlled:: -* Aspect Effective_Reads:: -* Aspect Effective_Writes:: -* Aspect Extensions_Visible:: -* Aspect Favor_Top_Level:: -* Aspect Ghost:: -* Aspect Global:: -* Aspect Initial_Condition:: -* Aspect Initializes:: -* Aspect Inline_Always:: -* Aspect Invariant:: -* Aspect Invariant’Class:: -* Aspect Iterable:: -* Aspect Linker_Section:: -* Aspect Lock_Free:: -* Aspect Max_Queue_Length:: -* Aspect No_Caching:: -* Aspect No_Elaboration_Code_All:: -* Aspect No_Inline:: -* Aspect No_Tagged_Streams:: -* Aspect No_Task_Parts:: -* Aspect Object_Size:: -* Aspect Obsolescent:: -* Aspect Part_Of:: -* Aspect Persistent_BSS:: -* Aspect Predicate:: -* Aspect Pure_Function:: -* Aspect Refined_Depends:: -* Aspect Refined_Global:: -* Aspect Refined_Post:: -* Aspect Refined_State:: -* Aspect Relaxed_Initialization:: -* Aspect Remote_Access_Type:: -* Aspect Secondary_Stack_Size:: -* Aspect Scalar_Storage_Order:: -* Aspect Shared:: -* Aspect Simple_Storage_Pool:: -* Aspect Simple_Storage_Pool_Type:: -* Aspect SPARK_Mode:: -* Aspect Suppress_Debug_Info:: -* Aspect Suppress_Initialization:: -* Aspect Test_Case:: -* Aspect Thread_Local_Storage:: -* Aspect Universal_Aliasing:: -* Aspect Unmodified:: -* Aspect Unreferenced:: -* Aspect Unreferenced_Objects:: -* Aspect Value_Size:: -* Aspect Volatile_Full_Access:: -* Aspect Volatile_Function:: -* Aspect Warnings:: - -@end menu - -@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{121} -@section Aspect Abstract_State - - -@geindex Abstract_State - -This aspect is equivalent to @ref{1e,,pragma Abstract_State}. - -@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{122} -@section Aspect Annotate - - -@geindex Annotate - -There are three forms of this aspect (where ID is an identifier, -and ARG is a general expression), -corresponding to @ref{29,,pragma Annotate}. - - -@table @asis - -@item `Annotate => ID' - -Equivalent to @code{pragma Annotate (ID, Entity => Name);} - -@item `Annotate => (ID)' - -Equivalent to @code{pragma Annotate (ID, Entity => Name);} - -@item `Annotate => (ID ,ID @{, ARG@})' - -Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} -@end table - -@node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{123} -@section Aspect Async_Readers - - -@geindex Async_Readers - -This boolean aspect is equivalent to @ref{30,,pragma Async_Readers}. - -@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{124} -@section Aspect Async_Writers - - -@geindex Async_Writers - -This boolean aspect is equivalent to @ref{32,,pragma Async_Writers}. - -@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{125} -@section Aspect Constant_After_Elaboration - - -@geindex Constant_After_Elaboration - -This aspect is equivalent to @ref{42,,pragma Constant_After_Elaboration}. - -@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{126} -@section Aspect Contract_Cases - - -@geindex Contract_Cases - -This aspect is equivalent to @ref{44,,pragma Contract_Cases}, the sequence -of clauses being enclosed in parentheses so that syntactically it is an -aggregate. - -@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{127} -@section Aspect Depends - - -@geindex Depends - -This aspect is equivalent to @ref{54,,pragma Depends}. - -@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{128} -@section Aspect Default_Initial_Condition - - -@geindex Default_Initial_Condition - -This aspect is equivalent to @ref{4e,,pragma Default_Initial_Condition}. - -@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{129} -@section Aspect Dimension - - -@geindex Dimension - -The @code{Dimension} aspect is used to specify the dimensions of a given -subtype of a dimensioned numeric type. The aspect also specifies a symbol -used when doing formatted output of dimensioned quantities. The syntax is: - -@example -with Dimension => - ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) - -SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL - -DIMENSION_VALUE ::= - RATIONAL -| others => RATIONAL -| DISCRETE_CHOICE_LIST => RATIONAL - -RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] -@end example - -This aspect can only be applied to a subtype whose parent type has -a @code{Dimension_System} aspect. The aspect must specify values for -all dimensions of the system. The rational values are the powers of the -corresponding dimensions that are used by the compiler to verify that -physical (numeric) computations are dimensionally consistent. For example, -the computation of a force must result in dimensions (L => 1, M => 1, T => -2). -For further examples of the usage -of this aspect, see package @code{System.Dim.Mks}. -Note that when the dimensioned type is an integer type, then any -dimension value must be an integer literal. - -@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12a} -@section Aspect Dimension_System - - -@geindex Dimension_System - -The @code{Dimension_System} aspect is used to define a system of -dimensions that will be used in subsequent subtype declarations with -@code{Dimension} aspects that reference this system. The syntax is: - -@example -with Dimension_System => (DIMENSION @{, DIMENSION@}); - -DIMENSION ::= ([Unit_Name =>] IDENTIFIER, - [Unit_Symbol =>] SYMBOL, - [Dim_Symbol =>] SYMBOL) - -SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL -@end example - -This aspect is applied to a type, which must be a numeric derived type -(typically a floating-point type), that -will represent values within the dimension system. Each @code{DIMENSION} -corresponds to one particular dimension. A maximum of 7 dimensions may -be specified. @code{Unit_Name} is the name of the dimension (for example -@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities -of this dimension (for example @code{m} for @code{Meter}). -@code{Dim_Symbol} gives -the identification within the dimension system (typically this is a -single letter, e.g. @code{L} standing for length for unit name @code{Meter}). -The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. -The @code{Dim_Symbol} is used in error messages when numeric operations have -inconsistent dimensions. - -GNAT provides the standard definition of the International MKS system in -the run-time package @code{System.Dim.Mks}. You can easily define -similar packages for cgs units or British units, and define conversion factors -between values in different systems. The MKS system is characterized by the -following aspect: - -@example -type Mks_Type is new Long_Long_Float with - Dimension_System => ( - (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), - (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), - (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), - (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), - (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), - (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), - (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); -@end example - -Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to -represent a theta character (avoiding the use of extended Latin-1 -characters in this context). - -See section ‘Performing Dimensionality Analysis in GNAT’ in the GNAT Users -Guide for detailed examples of use of the dimension system. - -@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12b} -@section Aspect Disable_Controlled - - -@geindex Disable_Controlled - -The aspect @code{Disable_Controlled} is defined for controlled record types. If -active, this aspect causes suppression of all related calls to @code{Initialize}, -@code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, -where for example you might want a record to be controlled or not depending on -whether some run-time check is enabled or suppressed. - -@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{12c} -@section Aspect Effective_Reads - - -@geindex Effective_Reads - -This aspect is equivalent to @ref{59,,pragma Effective_Reads}. - -@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{12d} -@section Aspect Effective_Writes - - -@geindex Effective_Writes - -This aspect is equivalent to @ref{5b,,pragma Effective_Writes}. - -@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{12e} -@section Aspect Extensions_Visible - - -@geindex Extensions_Visible - -This aspect is equivalent to @ref{66,,pragma Extensions_Visible}. - -@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{12f} -@section Aspect Favor_Top_Level - - -@geindex Favor_Top_Level - -This boolean aspect is equivalent to @ref{6b,,pragma Favor_Top_Level}. - -@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{130} -@section Aspect Ghost - - -@geindex Ghost - -This aspect is equivalent to @ref{6f,,pragma Ghost}. - -@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{131} -@section Aspect Global - - -@geindex Global - -This aspect is equivalent to @ref{71,,pragma Global}. - -@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{132} -@section Aspect Initial_Condition - - -@geindex Initial_Condition - -This aspect is equivalent to @ref{7e,,pragma Initial_Condition}. - -@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{133} -@section Aspect Initializes - - -@geindex Initializes - -This aspect is equivalent to @ref{81,,pragma Initializes}. - -@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{134} -@section Aspect Inline_Always - - -@geindex Inline_Always - -This boolean aspect is equivalent to @ref{83,,pragma Inline_Always}. - -@node Aspect Invariant,Aspect Invariant’Class,Aspect Inline_Always,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{135} -@section Aspect Invariant - - -@geindex Invariant - -This aspect is equivalent to @ref{8a,,pragma Invariant}. It is a -synonym for the language defined aspect @code{Type_Invariant} except -that it is separately controllable using pragma @code{Assertion_Policy}. - -@node Aspect Invariant’Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{136} -@section Aspect Invariant’Class - - -@geindex Invariant'Class - -This aspect is equivalent to @ref{101,,pragma Type_Invariant_Class}. It is a -synonym for the language defined aspect @code{Type_Invariant'Class} except -that it is separately controllable using pragma @code{Assertion_Policy}. - -@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant’Class,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{137} -@section Aspect Iterable - - -@geindex Iterable - -This aspect provides a light-weight mechanism for loops and quantified -expressions over container types, without the overhead imposed by the tampering -checks of standard Ada 2012 iterators. The value of the aspect is an aggregate -with six named components, of which the last three are optional: @code{First}, -@code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. -When only the first three components are specified, only the -@code{for .. in} form of iteration over cursors is available. When @code{Element} -is specified, both this form and the @code{for .. of} form of iteration over -elements are available. If the last two components are specified, reverse -iterations over the container can be specified (analogous to what can be done -over predefined containers that support the @code{Reverse_Iterator} interface). -The following is a typical example of use: - -@example -type List is private with - Iterable => (First => First_Cursor, - Next => Advance, - Has_Element => Cursor_Has_Element - [,Element => Get_Element] - [,Last => Last_Cursor] - [,Previous => Retreat]); -@end example - - -@itemize * - -@item -The values of @code{First} and @code{Last} are primitive operations of the -container type that return a @code{Cursor}, which must be a type declared in -the container package or visible from it. For example: -@end itemize - -@example -function First_Cursor (Cont : Container) return Cursor; -function Last_Cursor (Cont : Container) return Cursor; -@end example - - -@itemize * - -@item -The values of @code{Next} and @code{Previous} are primitive operations of the container type that take -both a container and a cursor and yield a cursor. For example: -@end itemize - -@example -function Advance (Cont : Container; Position : Cursor) return Cursor; -function Retreat (Cont : Container; Position : Cursor) return Cursor; -@end example - - -@itemize * - -@item -The value of @code{Has_Element} is a primitive operation of the container type -that takes both a container and a cursor and yields a boolean. For example: -@end itemize - -@example -function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; -@end example - - -@itemize * - -@item -The value of @code{Element} is a primitive operation of the container type that -takes both a container and a cursor and yields an @code{Element_Type}, which must -be a type declared in the container package or visible from it. For example: -@end itemize - -@example -function Get_Element (Cont : Container; Position : Cursor) return Element_Type; -@end example - -This aspect is used in the GNAT-defined formal container packages. - -@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{138} -@section Aspect Linker_Section - - -@geindex Linker_Section - -This aspect is equivalent to @ref{92,,pragma Linker_Section}. - -@node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{139} -@section Aspect Lock_Free - - -@geindex Lock_Free - -This boolean aspect is equivalent to @ref{94,,pragma Lock_Free}. - -@node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13a} -@section Aspect Max_Queue_Length - - -@geindex Max_Queue_Length - -This aspect is equivalent to @ref{9c,,pragma Max_Queue_Length}. - -@node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{13b} -@section Aspect No_Caching - - -@geindex No_Caching - -This boolean aspect is equivalent to @ref{9f,,pragma No_Caching}. - -@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13c} -@section Aspect No_Elaboration_Code_All - - -@geindex No_Elaboration_Code_All - -This aspect is equivalent to @ref{a2,,pragma No_Elaboration_Code_All} -for a program unit. - -@node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{13d} -@section Aspect No_Inline - - -@geindex No_Inline - -This boolean aspect is equivalent to @ref{a5,,pragma No_Inline}. - -@node Aspect No_Tagged_Streams,Aspect No_Task_Parts,Aspect No_Inline,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{13e} -@section Aspect No_Tagged_Streams - - -@geindex No_Tagged_Streams - -This aspect is equivalent to @ref{a9,,pragma No_Tagged_Streams} with an -argument specifying a root tagged type (thus this aspect can only be -applied to such a type). - -@node Aspect No_Task_Parts,Aspect Object_Size,Aspect No_Tagged_Streams,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-no-task-parts}@anchor{13f} -@section Aspect No_Task_Parts - - -@geindex No_Task_Parts - -Applies to a type. If True, requires that the type and any descendants -do not have any task parts. The rules for this aspect are the same as -for the language-defined No_Controlled_Parts aspect (see RM-H.4.1), -replacing “controlled” with “task”. - -If No_Task_Parts is True for a type T, then the compiler can optimize -away certain tasking-related code that would otherwise be needed -for T’Class, because descendants of T might contain tasks. - -@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Task_Parts,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{140} -@section Aspect Object_Size - - -@geindex Object_Size - -This aspect is equivalent to @ref{141,,attribute Object_Size}. - -@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{142} -@section Aspect Obsolescent - - -@geindex Obsolescent - -This aspect is equivalent to @ref{ac,,pragma Obsolescent}. Note that the -evaluation of this aspect happens at the point of occurrence, it is not -delayed until the freeze point. - -@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{143} -@section Aspect Part_Of - - -@geindex Part_Of - -This aspect is equivalent to @ref{b3,,pragma Part_Of}. - -@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{144} -@section Aspect Persistent_BSS - - -@geindex Persistent_BSS - -This boolean aspect is equivalent to @ref{b6,,pragma Persistent_BSS}. - -@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{145} -@section Aspect Predicate - - -@geindex Predicate - -This aspect is equivalent to @ref{bd,,pragma Predicate}. It is thus -similar to the language defined aspects @code{Dynamic_Predicate} -and @code{Static_Predicate} except that whether the resulting -predicate is static or dynamic is controlled by the form of the -expression. It is also separately controllable using pragma -@code{Assertion_Policy}. - -@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{146} -@section Aspect Pure_Function - - -@geindex Pure_Function - -This boolean aspect is equivalent to @ref{c9,,pragma Pure_Function}. - -@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{147} -@section Aspect Refined_Depends - - -@geindex Refined_Depends - -This aspect is equivalent to @ref{cd,,pragma Refined_Depends}. - -@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{148} -@section Aspect Refined_Global - - -@geindex Refined_Global - -This aspect is equivalent to @ref{cf,,pragma Refined_Global}. - -@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{149} -@section Aspect Refined_Post - - -@geindex Refined_Post - -This aspect is equivalent to @ref{d1,,pragma Refined_Post}. - -@node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{14a} -@section Aspect Refined_State - - -@geindex Refined_State - -This aspect is equivalent to @ref{d3,,pragma Refined_State}. - -@node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{14b} -@section Aspect Relaxed_Initialization - - -@geindex Refined_Initialization - -For the syntax and semantics of this aspect, see the SPARK 2014 Reference -Manual, section 6.10. - -@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{14c} -@section Aspect Remote_Access_Type - - -@geindex Remote_Access_Type - -This aspect is equivalent to @ref{d6,,pragma Remote_Access_Type}. - -@node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{14d} -@section Aspect Secondary_Stack_Size - - -@geindex Secondary_Stack_Size - -This aspect is equivalent to @ref{dc,,pragma Secondary_Stack_Size}. - -@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{14e} -@section Aspect Scalar_Storage_Order - - -@geindex Scalar_Storage_Order - -This aspect is equivalent to a @ref{14f,,attribute Scalar_Storage_Order}. - -@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{150} -@section Aspect Shared - - -@geindex Shared - -This boolean aspect is equivalent to @ref{df,,pragma Shared} -and is thus a synonym for aspect @code{Atomic}. - -@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{151} -@section Aspect Simple_Storage_Pool - - -@geindex Simple_Storage_Pool - -This aspect is equivalent to @ref{e4,,attribute Simple_Storage_Pool}. - -@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{152} -@section Aspect Simple_Storage_Pool_Type - - -@geindex Simple_Storage_Pool_Type - -This boolean aspect is equivalent to @ref{e3,,pragma Simple_Storage_Pool_Type}. - -@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{153} -@section Aspect SPARK_Mode - - -@geindex SPARK_Mode - -This aspect is equivalent to @ref{eb,,pragma SPARK_Mode} and -may be specified for either or both of the specification and body -of a subprogram or package. - -@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{154} -@section Aspect Suppress_Debug_Info - - -@geindex Suppress_Debug_Info - -This boolean aspect is equivalent to @ref{f3,,pragma Suppress_Debug_Info}. - -@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{155} -@section Aspect Suppress_Initialization - - -@geindex Suppress_Initialization - -This boolean aspect is equivalent to @ref{f6,,pragma Suppress_Initialization}. - -@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{156} -@section Aspect Test_Case - - -@geindex Test_Case - -This aspect is equivalent to @ref{fa,,pragma Test_Case}. - -@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{157} -@section Aspect Thread_Local_Storage - - -@geindex Thread_Local_Storage - -This boolean aspect is equivalent to @ref{fc,,pragma Thread_Local_Storage}. - -@node Aspect Universal_Aliasing,Aspect Unmodified,Aspect Thread_Local_Storage,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{158} -@section Aspect Universal_Aliasing - - -@geindex Universal_Aliasing - -This boolean aspect is equivalent to @ref{106,,pragma Universal_Aliasing}. - -@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Aliasing,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{159} -@section Aspect Unmodified - - -@geindex Unmodified - -This boolean aspect is equivalent to @ref{108,,pragma Unmodified}. - -@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{15a} -@section Aspect Unreferenced - - -@geindex Unreferenced - -This boolean aspect is equivalent to @ref{10a,,pragma Unreferenced}. - -When using the @code{-gnat2022} switch, this aspect is also supported on formal -parameters, which is in particular the only form possible for expression -functions. - -@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{15b} -@section Aspect Unreferenced_Objects - - -@geindex Unreferenced_Objects - -This boolean aspect is equivalent to @ref{10c,,pragma Unreferenced_Objects}. - -@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{15c} -@section Aspect Value_Size - - -@geindex Value_Size - -This aspect is equivalent to @ref{15d,,attribute Value_Size}. - -@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{15e} -@section Aspect Volatile_Full_Access - - -@geindex Volatile_Full_Access - -This boolean aspect is equivalent to @ref{116,,pragma Volatile_Full_Access}. - -@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{15f} -@section Aspect Volatile_Function - - -@geindex Volatile_Function - -This boolean aspect is equivalent to @ref{118,,pragma Volatile_Function}. - -@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{160} -@section Aspect Warnings - - -@geindex Warnings - -This aspect is equivalent to the two argument form of @ref{11a,,pragma Warnings}, -where the first argument is @code{ON} or @code{OFF} and the second argument -is the entity. - -@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top -@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{161}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{162}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8} -@chapter Implementation Defined Attributes - - -Ada defines (throughout the Ada reference manual, -summarized in Annex K), -a set of attributes that provide useful additional functionality in all -areas of the language. These language defined attributes are implemented -in GNAT and work as described in the Ada Reference Manual. - -In addition, Ada allows implementations to define additional -attributes whose meaning is defined by the implementation. GNAT provides -a number of these implementation-dependent attributes which can be used -to extend and enhance the functionality of the compiler. This section of -the GNAT reference manual describes these additional attributes. It also -describes additional implementation-dependent features of standard -language-defined attributes. - -Note that any program using these attributes may not be portable to -other compilers (although GNAT implements this set of attributes on all -platforms). Therefore if portability to other compilers is an important -consideration, you should minimize the use of these attributes. - -@menu -* Attribute Abort_Signal:: -* Attribute Address_Size:: -* Attribute Asm_Input:: -* Attribute Asm_Output:: -* Attribute Atomic_Always_Lock_Free:: -* Attribute Bit:: -* Attribute Bit_Position:: -* Attribute Code_Address:: -* Attribute Compiler_Version:: -* Attribute Constrained:: -* Attribute Default_Bit_Order:: -* Attribute Default_Scalar_Storage_Order:: -* Attribute Deref:: -* Attribute Descriptor_Size:: -* Attribute Elaborated:: -* Attribute Elab_Body:: -* Attribute Elab_Spec:: -* Attribute Elab_Subp_Body:: -* Attribute Emax:: -* Attribute Enabled:: -* Attribute Enum_Rep:: -* Attribute Enum_Val:: -* Attribute Epsilon:: -* Attribute Fast_Math:: -* Attribute Finalization_Size:: -* Attribute Fixed_Value:: -* Attribute From_Any:: -* Attribute Has_Access_Values:: -* Attribute Has_Discriminants:: -* Attribute Has_Tagged_Values:: -* Attribute Img:: -* Attribute Initialized:: -* Attribute Integer_Value:: -* Attribute Invalid_Value:: -* Attribute Iterable:: -* Attribute Large:: -* Attribute Library_Level:: -* Attribute Loop_Entry:: -* Attribute Machine_Size:: -* Attribute Mantissa:: -* Attribute Maximum_Alignment:: -* Attribute Max_Integer_Size:: -* Attribute Mechanism_Code:: -* Attribute Null_Parameter:: -* Attribute Object_Size:: -* Attribute Old:: -* Attribute Passed_By_Reference:: -* Attribute Pool_Address:: -* Attribute Range_Length:: -* Attribute Restriction_Set:: -* Attribute Result:: -* Attribute Safe_Emax:: -* Attribute Safe_Large:: -* Attribute Safe_Small:: -* Attribute Scalar_Storage_Order:: -* Attribute Simple_Storage_Pool:: -* Attribute Small:: -* Attribute Small_Denominator:: -* Attribute Small_Numerator:: -* Attribute Storage_Unit:: -* Attribute Stub_Type:: -* Attribute System_Allocator_Alignment:: -* Attribute Target_Name:: -* Attribute To_Address:: -* Attribute To_Any:: -* Attribute Type_Class:: -* Attribute Type_Key:: -* Attribute TypeCode:: -* Attribute Unconstrained_Array:: -* Attribute Universal_Literal_String:: -* Attribute Unrestricted_Access:: -* Attribute Update:: -* Attribute Valid_Value:: -* Attribute Valid_Scalars:: -* Attribute VADS_Size:: -* Attribute Value_Size:: -* Attribute Wchar_T_Size:: -* Attribute Word_Size:: - -@end menu - -@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{163} -@section Attribute Abort_Signal - - -@geindex Abort_Signal - -@code{Standard'Abort_Signal} (@code{Standard} is the only allowed -prefix) provides the entity for the special exception used to signal -task abort or asynchronous transfer of control. Normally this attribute -should only be used in the tasking runtime (it is highly peculiar, and -completely outside the normal semantics of Ada, for a user program to -intercept the abort exception). - -@node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{164} -@section Attribute Address_Size - - -@geindex Size of `@w{`}Address`@w{`} - -@geindex Address_Size - -@code{Standard'Address_Size} (@code{Standard} is the only allowed -prefix) is a static constant giving the number of bits in an -@code{Address}. It is the same value as System.Address’Size, -but has the advantage of being static, while a direct -reference to System.Address’Size is nonstatic because Address -is a private type. - -@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{165} -@section Attribute Asm_Input - - -@geindex Asm_Input - -The @code{Asm_Input} attribute denotes a function that takes two -parameters. The first is a string, the second is an expression of the -type designated by the prefix. The first (string) argument is required -to be a static expression, and is the constraint for the parameter, -(e.g., what kind of register is required). The second argument is the -value to be used as the input argument. The possible values for the -constant are the same as those used in the RTL, and are dependent on -the configuration file used to built the GCC back end. -@ref{166,,Machine Code Insertions} - -@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{167} -@section Attribute Asm_Output - - -@geindex Asm_Output - -The @code{Asm_Output} attribute denotes a function that takes two -parameters. The first is a string, the second is the name of a variable -of the type designated by the attribute prefix. The first (string) -argument is required to be a static expression and designates the -constraint for the parameter (e.g., what kind of register is -required). The second argument is the variable to be updated with the -result. The possible values for constraint are the same as those used in -the RTL, and are dependent on the configuration file used to build the -GCC back end. If there are no output operands, then this argument may -either be omitted, or explicitly given as @code{No_Output_Operands}. -@ref{166,,Machine Code Insertions} - -@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{168} -@section Attribute Atomic_Always_Lock_Free - - -@geindex Atomic_Always_Lock_Free - -The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. -The result is a Boolean value which is True if the type has discriminants, -and False otherwise. The result indicate whether atomic operations are -supported by the target for the given type. - -@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{169} -@section Attribute Bit - - -@geindex Bit - -@code{obj'Bit}, where @code{obj} is any object, yields the bit -offset within the storage unit (byte) that contains the first bit of -storage allocated for the object. The value of this attribute is of the -type `universal_integer' and is always a nonnegative number smaller -than @code{System.Storage_Unit}. - -For an object that is a variable or a constant allocated in a register, -the value is zero. (The use of this attribute does not force the -allocation of a variable to memory). - -For an object that is a formal parameter, this attribute applies -to either the matching actual parameter or to a copy of the -matching actual parameter. - -For an access object the value is zero. Note that -@code{obj.all'Bit} is subject to an @code{Access_Check} for the -designated object. Similarly for a record component -@code{X.C'Bit} is subject to a discriminant check and -@code{X(I).Bit} and @code{X(I1..I2)'Bit} -are subject to index checks. - -This attribute is designed to be compatible with the DEC Ada 83 definition -and implementation of the @code{Bit} attribute. - -@node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{16a} -@section Attribute Bit_Position - - -@geindex Bit_Position - -@code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one -of the fields of the record type, yields the bit -offset within the record contains the first bit of -storage allocated for the object. The value of this attribute is of the -type `universal_integer'. The value depends only on the field -@code{C} and is independent of the alignment of -the containing record @code{R}. - -@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{16b} -@section Attribute Code_Address - - -@geindex Code_Address - -@geindex Subprogram address - -@geindex Address of subprogram code - -The @code{'Address} -attribute may be applied to subprograms in Ada 95 and Ada 2005, but the -intended effect seems to be to provide -an address value which can be used to call the subprogram by means of -an address clause as in the following example: - -@example -procedure K is ... - -procedure L; -for L'Address use K'Address; -pragma Import (Ada, L); -@end example - -A call to @code{L} is then expected to result in a call to @code{K}. -In Ada 83, where there were no access-to-subprogram values, this was -a common work-around for getting the effect of an indirect call. -GNAT implements the above use of @code{Address} and the technique -illustrated by the example code works correctly. - -However, for some purposes, it is useful to have the address of the start -of the generated code for the subprogram. On some architectures, this is -not necessarily the same as the @code{Address} value described above. -For example, the @code{Address} value may reference a subprogram -descriptor rather than the subprogram itself. - -The @code{'Code_Address} attribute, which can only be applied to -subprogram entities, always returns the address of the start of the -generated code of the specified subprogram, which may or may not be -the same value as is returned by the corresponding @code{'Address} -attribute. - -@node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{16c} -@section Attribute Compiler_Version - - -@geindex Compiler_Version - -@code{Standard'Compiler_Version} (@code{Standard} is the only allowed -prefix) yields a static string identifying the version of the compiler -being used to compile the unit containing the attribute reference. - -@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{16d} -@section Attribute Constrained - - -@geindex Constrained - -In addition to the usage of this attribute in the Ada RM, GNAT -also permits the use of the @code{'Constrained} attribute -in a generic template -for any type, including types without discriminants. The value of this -attribute in the generic instance when applied to a scalar type or a -record type without discriminants is always @code{True}. This usage is -compatible with older Ada compilers, including notably DEC Ada. - -@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{16e} -@section Attribute Default_Bit_Order - - -@geindex Big endian - -@geindex Little endian - -@geindex Default_Bit_Order - -@code{Standard'Default_Bit_Order} (@code{Standard} is the only -allowed prefix), provides the value @code{System.Default_Bit_Order} -as a @code{Pos} value (0 for @code{High_Order_First}, 1 for -@code{Low_Order_First}). This is used to construct the definition of -@code{Default_Bit_Order} in package @code{System}. - -@node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{16f} -@section Attribute Default_Scalar_Storage_Order - - -@geindex Big endian - -@geindex Little endian - -@geindex Default_Scalar_Storage_Order - -@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only -allowed prefix), provides the current value of the default scalar storage -order (as specified using pragma @code{Default_Scalar_Storage_Order}, or -equal to @code{Default_Bit_Order} if unspecified) as a -@code{System.Bit_Order} value. This is a static attribute. - -@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{170} -@section Attribute Deref - - -@geindex Deref - -The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields -the variable of type @code{typ} that is located at the given address. It is similar -to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to -a named access-to-@cite{typ} type, except that it yields a variable, so it can be -used on the left side of an assignment. - -@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{171} -@section Attribute Descriptor_Size - - -@geindex Descriptor - -@geindex Dope vector - -@geindex Descriptor_Size - -Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the -descriptor allocated for a type. The result is non-zero only for unconstrained -array types and the returned value is of type universal integer. In GNAT, an -array descriptor contains bounds information and is located immediately before -the first element of the array. - -@example -type Unconstr_Array is array (Short_Short_Integer range <>) of Positive; -Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); -@end example - -The attribute takes into account any padding due to the alignment of the -component type. In the example above, the descriptor contains two values -of type @code{Short_Short_Integer} representing the low and high bound. But, -since @code{Positive} has an alignment of 4, the size of the descriptor is -@code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32, -which yields a size of 32 bits, i.e. including 16 bits of padding. - -@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{172} -@section Attribute Elaborated - - -@geindex Elaborated - -The prefix of the @code{'Elaborated} attribute must be a unit name. The -value is a Boolean which indicates whether or not the given unit has been -elaborated. This attribute is primarily intended for internal use by the -generated code for dynamic elaboration checking, but it can also be used -in user programs. The value will always be True once elaboration of all -units has been completed. An exception is for units which need no -elaboration, the value is always False for such units. - -@node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{173} -@section Attribute Elab_Body - - -@geindex Elab_Body - -This attribute can only be applied to a program unit name. It returns -the entity for the corresponding elaboration procedure for elaborating -the body of the referenced unit. This is used in the main generated -elaboration procedure by the binder and is not normally used in any -other context. However, there may be specialized situations in which it -is useful to be able to call this elaboration procedure from Ada code, -e.g., if it is necessary to do selective re-elaboration to fix some -error. - -@node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{174} -@section Attribute Elab_Spec - - -@geindex Elab_Spec - -This attribute can only be applied to a program unit name. It returns -the entity for the corresponding elaboration procedure for elaborating -the spec of the referenced unit. This is used in the main -generated elaboration procedure by the binder and is not normally used -in any other context. However, there may be specialized situations in -which it is useful to be able to call this elaboration procedure from -Ada code, e.g., if it is necessary to do selective re-elaboration to fix -some error. - -@node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{175} -@section Attribute Elab_Subp_Body - - -@geindex Elab_Subp_Body - -This attribute can only be applied to a library level subprogram -name and is only allowed in CodePeer mode. It returns the entity -for the corresponding elaboration procedure for elaborating the body -of the referenced subprogram unit. This is used in the main generated -elaboration procedure by the binder in CodePeer mode only and is unrecognized -otherwise. - -@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{176} -@section Attribute Emax - - -@geindex Ada 83 attributes - -@geindex Emax - -The @code{Emax} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{177} -@section Attribute Enabled - - -@geindex Enabled - -The @code{Enabled} attribute allows an application program to check at compile -time to see if the designated check is currently enabled. The prefix is a -simple identifier, referencing any predefined check name (other than -@code{All_Checks}) or a check name introduced by pragma Check_Name. If -no argument is given for the attribute, the check is for the general state -of the check, if an argument is given, then it is an entity name, and the -check indicates whether an @code{Suppress} or @code{Unsuppress} has been -given naming the entity (if not, then the argument is ignored). - -Note that instantiations inherit the check status at the point of the -instantiation, so a useful idiom is to have a library package that -introduces a check name with @code{pragma Check_Name}, and then contains -generic packages or subprograms which use the @code{Enabled} attribute -to see if the check is enabled. A user of this package can then issue -a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating -the package or subprogram, controlling whether the check will be present. - -@node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{178} -@section Attribute Enum_Rep - - -@geindex Representation of enums - -@geindex Enum_Rep - -Note that this attribute is now standard in Ada 202x and is available -as an implementation defined attribute for earlier Ada versions. - -For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a -function with the following spec: - -@example -function S'Enum_Rep (Arg : S'Base) return ; -@end example - -It is also allowable to apply @code{Enum_Rep} directly to an object of an -enumeration type or to a non-overloaded enumeration -literal. In this case @code{S'Enum_Rep} is equivalent to -@code{typ'Enum_Rep(S)} where @code{typ} is the type of the -enumeration literal or object. - -The function returns the representation value for the given enumeration -value. This will be equal to value of the @code{Pos} attribute in the -absence of an enumeration representation clause. This is a static -attribute (i.e., the result is static if the argument is static). - -@code{S'Enum_Rep} can also be used with integer types and objects, -in which case it simply returns the integer value. The reason for this -is to allow it to be used for @code{(<>)} discrete formal arguments in -a generic unit that can be instantiated with either enumeration types -or integer types. Note that if @code{Enum_Rep} is used on a modular -type whose upper bound exceeds the upper bound of the largest signed -integer type, and the argument is a variable, so that the universal -integer calculation is done at run time, then the call to @code{Enum_Rep} -may raise @code{Constraint_Error}. - -@node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{179} -@section Attribute Enum_Val - - -@geindex Representation of enums - -@geindex Enum_Val - -Note that this attribute is now standard in Ada 202x and is available -as an implementation defined attribute for earlier Ada versions. - -For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a -function with the following spec: - -@example -function S'Enum_Val (Arg : ) return S'Base; -@end example - -The function returns the enumeration value whose representation matches the -argument, or raises Constraint_Error if no enumeration literal of the type -has the matching value. -This will be equal to value of the @code{Val} attribute in the -absence of an enumeration representation clause. This is a static -attribute (i.e., the result is static if the argument is static). - -@node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{17a} -@section Attribute Epsilon - - -@geindex Ada 83 attributes - -@geindex Epsilon - -The @code{Epsilon} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{17b} -@section Attribute Fast_Math - - -@geindex Fast_Math - -@code{Standard'Fast_Math} (@code{Standard} is the only allowed -prefix) yields a static Boolean value that is True if pragma -@code{Fast_Math} is active, and False otherwise. - -@node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{17c} -@section Attribute Finalization_Size - - -@geindex Finalization_Size - -The prefix of attribute @code{Finalization_Size} must be an object or -a non-class-wide type. This attribute returns the size of any hidden data -reserved by the compiler to handle finalization-related actions. The type of -the attribute is `universal_integer'. - -@code{Finalization_Size} yields a value of zero for a type with no controlled -parts, an object whose type has no controlled parts, or an object of a -class-wide type whose tag denotes a type with no controlled parts. - -Note that only heap-allocated objects contain finalization data. - -@node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{17d} -@section Attribute Fixed_Value - - -@geindex Fixed_Value - -For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a -function with the following specification: - -@example -function S'Fixed_Value (Arg : ) return S; -@end example - -The value returned is the fixed-point value @code{V} such that: - -@example -V = Arg * S'Small -@end example - -The effect is thus similar to first converting the argument to the -integer type used to represent @code{S}, and then doing an unchecked -conversion to the fixed-point type. The difference is -that there are full range checks, to ensure that the result is in range. -This attribute is primarily intended for use in implementation of the -input-output functions for fixed-point values. - -@node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{17e} -@section Attribute From_Any - - -@geindex From_Any - -This internal attribute is used for the generation of remote subprogram -stubs in the context of the Distributed Systems Annex. - -@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{17f} -@section Attribute Has_Access_Values - - -@geindex Access values -@geindex testing for - -@geindex Has_Access_Values - -The prefix of the @code{Has_Access_Values} attribute is a type. The result -is a Boolean value which is True if the is an access type, or is a composite -type with a component (at any nesting depth) that is an access type, and is -False otherwise. -The intended use of this attribute is in conjunction with generic -definitions. If the attribute is applied to a generic private type, it -indicates whether or not the corresponding actual type has access values. - -@node Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{180} -@section Attribute Has_Discriminants - - -@geindex Discriminants -@geindex testing for - -@geindex Has_Discriminants - -The prefix of the @code{Has_Discriminants} attribute is a type. The result -is a Boolean value which is True if the type has discriminants, and False -otherwise. The intended use of this attribute is in conjunction with generic -definitions. If the attribute is applied to a generic private type, it -indicates whether or not the corresponding actual type has discriminants. - -@node Attribute Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{181} -@section Attribute Has_Tagged_Values - - -@geindex Tagged values -@geindex testing for - -@geindex Has_Tagged_Values - -The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a -Boolean value which is True if the type is a composite type (array or record) -that is either a tagged type or has a subcomponent that is tagged, and is False -otherwise. The intended use of this attribute is in conjunction with generic -definitions. If the attribute is applied to a generic private type, it -indicates whether or not the corresponding actual type has access values. - -@node Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{182} -@section Attribute Img - - -@geindex Img - -The @code{Img} attribute differs from @code{Image} in that, while both can be -applied directly to an object, @code{Img} cannot be applied to types. - -Example usage of the attribute: - -@example -Put_Line ("X = " & X'Img); -@end example - -which has the same meaning as the more verbose: - -@example -Put_Line ("X = " & T'Image (X)); -@end example - -where @code{T} is the (sub)type of the object @code{X}. - -Note that technically, in analogy to @code{Image}, -@code{X'Img} returns a parameterless function -that returns the appropriate string when called. This means that -@code{X'Img} can be renamed as a function-returning-string, or used -in an instantiation as a function parameter. - -@node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{183} -@section Attribute Initialized - - -@geindex Initialized - -For the syntax and semantics of this attribute, see the SPARK 2014 Reference -Manual, section 6.10. - -@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{184} -@section Attribute Integer_Value - - -@geindex Integer_Value - -For every integer type @code{S}, @code{S'Integer_Value} denotes a -function with the following spec: - -@example -function S'Integer_Value (Arg : ) return S; -@end example - -The value returned is the integer value @code{V}, such that: - -@example -Arg = V * T'Small -@end example - -where @code{T} is the type of @code{Arg}. -The effect is thus similar to first doing an unchecked conversion from -the fixed-point type to its corresponding implementation type, and then -converting the result to the target integer type. The difference is -that there are full range checks, to ensure that the result is in range. -This attribute is primarily intended for use in implementation of the -standard input-output functions for fixed-point values. - -@node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{185} -@section Attribute Invalid_Value - - -@geindex Invalid_Value - -For every scalar type S, S’Invalid_Value returns an undefined value of the -type. If possible this value is an invalid representation for the type. The -value returned is identical to the value used to initialize an otherwise -uninitialized value of the type if pragma Initialize_Scalars is used, -including the ability to modify the value with the binder -Sxx flag and -relevant environment variables at run time. - -@node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{186} -@section Attribute Iterable - - -@geindex Iterable - -Equivalent to Aspect Iterable. - -@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{187} -@section Attribute Large - - -@geindex Ada 83 attributes - -@geindex Large - -The @code{Large} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Library_Level,Attribute Loop_Entry,Attribute Large,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{188} -@section Attribute Library_Level - - -@geindex Library_Level - -@code{P'Library_Level}, where P is an entity name, -returns a Boolean value which is True if the entity is declared -at the library level, and False otherwise. Note that within a -generic instantiation, the name of the generic unit denotes the -instance, which means that this attribute can be used to test -if a generic is instantiated at the library level, as shown -in this example: - -@example -generic - ... -package Gen is - pragma Compile_Time_Error - (not Gen'Library_Level, - "Gen can only be instantiated at library level"); - ... -end Gen; -@end example - -@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Library_Level,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{189} -@section Attribute Loop_Entry - - -@geindex Loop_Entry - -Syntax: - -@example -X'Loop_Entry [(loop_name)] -@end example - -The @code{Loop_Entry} attribute is used to refer to the value that an -expression had upon entry to a given loop in much the same way that the -@code{Old} attribute in a subprogram postcondition can be used to refer -to the value an expression had upon entry to the subprogram. The -relevant loop is either identified by the given loop name, or it is the -innermost enclosing loop when no loop name is given. - -A @code{Loop_Entry} attribute can only occur within an @code{Assert}, -@code{Assert_And_Cut}, @code{Assume}, @code{Loop_Variant} or @code{Loop_Invariant} pragma. -In addition, such a pragma must be one of the items in the sequence -of statements of a loop body, or nested inside block statements that -appear in the sequence of statements of a loop body. -A common use of @code{Loop_Entry} is to compare the current value of objects with -their initial value at loop entry, in a @code{Loop_Invariant} pragma. - -The effect of using @code{X'Loop_Entry} is the same as declaring -a constant initialized with the initial value of @code{X} at loop -entry. This copy is not performed if the loop is not entered, or if the -corresponding pragmas are ignored or disabled. - -@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{18a} -@section Attribute Machine_Size - - -@geindex Machine_Size - -This attribute is identical to the @code{Object_Size} attribute. It is -provided for compatibility with the DEC Ada 83 attribute of this name. - -@node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{18b} -@section Attribute Mantissa - - -@geindex Ada 83 attributes - -@geindex Mantissa - -The @code{Mantissa} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Maximum_Alignment,Attribute Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{18c}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{18d} -@section Attribute Maximum_Alignment - - -@geindex Alignment -@geindex maximum - -@geindex Maximum_Alignment - -@code{Standard'Maximum_Alignment} (@code{Standard} is the only -allowed prefix) provides the maximum useful alignment value for the -target. This is a static value that can be used to specify the alignment -for an object, guaranteeing that it is properly aligned in all -cases. - -@node Attribute Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{18e} -@section Attribute Max_Integer_Size - - -@geindex Max_Integer_Size - -@code{Standard'Max_Integer_Size} (@code{Standard} is the only allowed -prefix) provides the size of the largest supported integer type for -the target. The result is a static constant. - -@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{18f} -@section Attribute Mechanism_Code - - -@geindex Return values -@geindex passing mechanism - -@geindex Parameters -@geindex passing mechanism - -@geindex Mechanism_Code - -@code{func'Mechanism_Code} yields an integer code for the -mechanism used for the result of function @code{func}, and -@code{subprog'Mechanism_Code (n)} yields the mechanism -used for formal parameter number `n' (a static integer value, with 1 -meaning the first parameter) of subprogram @code{subprog}. The code returned is: - - -@table @asis - -@item `1' - -by copy (value) - -@item `2' - -by reference -@end table - -@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{190} -@section Attribute Null_Parameter - - -@geindex Zero address -@geindex passing - -@geindex Null_Parameter - -A reference @code{T'Null_Parameter} denotes an imaginary object of -type or subtype @code{T} allocated at machine address zero. The attribute -is allowed only as the default expression of a formal parameter, or as -an actual expression of a subprogram call. In either case, the -subprogram must be imported. - -The identity of the object is represented by the address zero in the -argument list, independent of the passing mechanism (explicit or -default). - -This capability is needed to specify that a zero address should be -passed for a record or other composite object passed by reference. -There is no way of indicating this without the @code{Null_Parameter} -attribute. - -@node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{141}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{191} -@section Attribute Object_Size - - -@geindex Size -@geindex used for objects - -@geindex Object_Size - -The size of an object is not necessarily the same as the size of the type -of an object. This is because by default object sizes are increased to be -a multiple of the alignment of the object. For example, -@code{Natural'Size} is -31, but by default objects of type @code{Natural} will have a size of 32 bits. -Similarly, a record containing an integer and a character: - -@example -type Rec is record - I : Integer; - C : Character; -end record; -@end example - -will have a size of 40 (that is @code{Rec'Size} will be 40). The -alignment will be 4, because of the -integer field, and so the default size of record objects for this type -will be 64 (8 bytes). - -If the alignment of the above record is specified to be 1, then the -object size will be 40 (5 bytes). This is true by default, and also -an object size of 40 can be explicitly specified in this case. - -A consequence of this capability is that different object sizes can be -given to subtypes that would otherwise be considered in Ada to be -statically matching. But it makes no sense to consider such subtypes -as statically matching. Consequently, GNAT adds a rule -to the static matching rules that requires object sizes to match. -Consider this example: - -@example - 1. procedure BadAVConvert is - 2. type R is new Integer; - 3. subtype R1 is R range 1 .. 10; - 4. subtype R2 is R range 1 .. 10; - 5. for R1'Object_Size use 8; - 6. for R2'Object_Size use 16; - 7. type R1P is access all R1; - 8. type R2P is access all R2; - 9. R1PV : R1P := new R1'(4); -10. R2PV : R2P; -11. begin -12. R2PV := R2P (R1PV); - | - >>> target designated subtype not compatible with - type "R1" defined at line 3 - -13. end; -@end example - -In the absence of lines 5 and 6, -types @code{R1} and @code{R2} statically match and -hence the conversion on line 12 is legal. But since lines 5 and 6 -cause the object sizes to differ, GNAT considers that types -@code{R1} and @code{R2} are not statically matching, and line 12 -generates the diagnostic shown above. - -Similar additional checks are performed in other contexts requiring -statically matching subtypes. - -@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{192} -@section Attribute Old - - -@geindex Old - -In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage -within @code{Post} aspect), GNAT also permits the use of this attribute -in implementation defined pragmas @code{Postcondition}, -@code{Contract_Cases} and @code{Test_Case}. Also usages of -@code{Old} which would be illegal according to the Ada 2012 RM -definition are allowed under control of -implementation defined pragma @code{Unevaluated_Use_Of_Old}. - -@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{193} -@section Attribute Passed_By_Reference - - -@geindex Parameters -@geindex when passed by reference - -@geindex Passed_By_Reference - -@code{typ'Passed_By_Reference} for any subtype @cite{typ} returns -a value of type @code{Boolean} value that is @code{True} if the type is -normally passed by reference and @code{False} if the type is normally -passed by copy in calls. For scalar types, the result is always @code{False} -and is static. For non-scalar types, the result is nonstatic. - -@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{194} -@section Attribute Pool_Address - - -@geindex Pool_Address - -@code{X'Pool_Address} for any object @code{X} returns the address -of X within its storage pool. This is the same as -@code{X'Address}, except that for an unconstrained array whose -bounds are allocated[...] [diff truncated at 524288 bytes]